user_exception.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
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
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
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.
15  */
16 
17 #ifndef ZORBA_USER_EXCEPTION_API_H
18 #define ZORBA_USER_EXCEPTION_API_H
19 
20 #include <vector>
21 
22 #include <zorba/api_shared_types.h>
23 #include <zorba/error.h>
24 #include <zorba/xquery_exception.h>
25 
26 namespace zorba {
27 
28 namespace serialization {
29  class Archiver;
30 }
31 
32 ///////////////////////////////////////////////////////////////////////////////
33 
34 class UserException;
35 
36 namespace internal {
37 
38 typedef std::vector<Item> error_object_type;
39 
40 /**
41  * \internal
42  * Makes a UserException.
43  * This function should not be called directly.
44  * Instead, the \c USER_EXCEPTION macro should be used.
45  *
46  * @param raise_file The C++ source-code file name whence the exception was
47  * raised.
48  * @param raise_line The C++ source-code line number whence the exception was
49  * raised.
50  * @param ns The error's namespace.
51  * @param prefix The error's prefix.
52  * @param localname The error's local-name.
53  * @param description The error description.
54  * @param loc The XQuery source-code location.
55  * @param error_object The error object, if any.
56  * @return Returns a new UserException.
57  */
58 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_4CC_EL_EOT_X
59 make_user_exception( char const *raise_file,
60  ZorbaException::line_type raise_line,
61  char const *ns, char const *prefix, char const *localname,
62  char const *description, diagnostic::location const &loc,
63  error_object_type *error_object = 0 );
64 
65 /**
66  * \internal
67  * Makes a UserException.
68  * This function should not be called directly.
69  * Instead, the \c USER_EXCEPTION macro should be used.
70  *
71  * @param raise_file The C++ source-code file name whence the exception was
72  * raised.
73  * @param raise_line The C++ source-code line number whence the exception was
74  * raised.
75  * @param error The error.
76  * @param description The error description.
77  * @param loc The XQuery source-code location.
78  * @param error_object The error object, if any.
79  * @return Returns a new UserException.
80  */
81 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_CC_EL_EOT_X
82 make_user_exception( char const *raise_file,
83  ZorbaException::line_type raise_line,
84  Error const &error, char const *description,
85  diagnostic::location const &loc,
86  error_object_type *error_object = 0 );
87 
88 } // namespace internal
89 
90 ///////////////////////////////////////////////////////////////////////////////
91 
92 /**
93  * A %UserException is-an XQueryException for errors raised via
94  * <code>fn:error()</code>.
95  */
96 class ZORBA_DLL_PUBLIC UserException : public XQueryException {
97 public:
99 
100  /**
101  * Copy-constructs a %UserException.
102  *
103  * @param from The %UserException to copy from.
104  */
105  UserException( UserException const &from );
106 
107  /**
108  * Destroys this %UserException.
109  */
110  ~UserException() throw();
111 
112  /**
113  * Assigns this %UserException from another.
114  *
115  * @param from The %UserException to assign from.
116  * @return Returns \c *this.
117  */
118  UserException& operator=( UserException const &from );
119 
120  /**
121  * Gets the error object associated with this exception.
122  *
123  * @return Returns said error object.
124  */
125  error_object_type const& error_object() const throw() {
126  return error_object_;
127  }
128 
129  // inherited
130  void polymorphic_throw() const;
131 
132 protected:
133  // inherited
134  std::unique_ptr<ZorbaException> clone() const;
135 
136 private:
137  error_object_type error_object_;
138 
139  /**
140  * Constructs a %UserException.
141  *
142  * @param ns The namespace of the error.
143  * @param prefix The prefix of the error.
144  * @param locaname The local-name of the error.
145  * @param raise_file The source-code file name whence the exception was
146  * raised.
147  * @param raise_line The source-code line number whence the exception was
148  * raised.
149  * @param description The error description.
150  * @param error_object The error object.
151  */
152  UserException( char const *ns, char const *prefix, char const *localname,
153  char const *raise_file, line_type raise_line,
154  char const *description, error_object_type *error_object );
155 
156  /**
157  * Constructs a %UserException.
158  *
159  * @param error The error.
160  * @param raise_file The source-code file name whence the exception was
161  * raised.
162  * @param raise_line The source-code line number whence the exception was
163  * raised.
164  * @param description The error description.
165  * @param error_object The error object.
166  */
167  UserException( Error const &error,
168  char const *raise_file, line_type raise_line,
169  char const *description, error_object_type *error_object );
170 
172  char const*, line_type, char const*, char const*, char const*, char const*,
174  );
175 
177  char const*, line_type, Error const&, char const*,
179  );
180 
181  // for plan serialization
182  UserException( serialization::Archiver& );
183  friend void serialization::operator&( serialization::Archiver&,
184  ZorbaException*& );
185 };
186 
187 /**
188  * Creates a UserException.
189  * \hideinitializer
190  */
191 #define USER_EXCEPTION(...) \
192  ::zorba::internal::make_user_exception( __FILE__, __LINE__, __VA_ARGS__ )
193 
194 /**
195  * Creates a default UserException.
196  * \hideinitializer
197  */
198 #define DEFAULT_USER_EXCEPTION() \
199  ::zorba::internal::make_user_exception( __FILE__, __LINE__ )
200 
201 ///////////////////////////////////////////////////////////////////////////////
202 
203 namespace internal {
204 
205 /**
206  * \internal
207  * Makes a UserException.
208  * This provides for the:
209  * \code
210  * fn:error()
211  * \endcode
212  * XQuery function.
213  * This function should not be called directly.
214  * Instead, the \c DEFAULT_USER_EXCEPTION macro should be used.
215  *
216  * @param raise_file The C++ source-code file name whence the exception was
217  * raised.
218  * @param raise_line The C++ source-code line number whence the exception was
219  * raised.
220  */
221 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_X
222 make_user_exception( char const *raise_file,
223  ZorbaException::line_type raise_line );
224 
225 /**
226  * \internal
227  * Makes a UserException.
228  * This provides for the:
229  * \code
230  * fn:error($error as xs:QName)
231  * \endcode
232  * XQuery function.
233  * This function should not be called directly.
234  * Instead, the \c USER_EXCEPTION macro should be used.
235  *
236  * @param raise_file The C++ source-code file name whence the exception was
237  * raised.
238  * @param raise_line The C++ source-code line number whence the exception was
239  * raised.
240  * @param error The error code expressed as a QName.
241  */
242 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_I_X
243 make_user_exception( char const *raise_file,
244  ZorbaException::line_type raise_line,
245  Item const &error );
246 
247 /**
248  * \internal
249  * Makes a UserException.
250  * This provides for the:
251  * \code
252  * fn:error($error as xs:QName)
253  * \endcode
254  * XQuery function.
255  * This function should not be called directly.
256  * Instead, the \c USER_EXCEPTION macro should be used.
257  *
258  * @param raise_file The C++ source-code file name whence the exception was
259  * raised.
260  * @param raise_line The C++ source-code line number whence the exception was
261  * raised.
262  * @param error The error code expressed as a QName.
263  */
264 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_X
265 make_user_exception( char const *raise_file,
266  ZorbaException::line_type raise_line,
267  Error const &error );
268 
269 /**
270  * \internal
271  * Makes a UserException.
272  * This provides for the:
273  * \code
274  * fn:error($error as xs:QName,
275  * $description as xs:string)
276  * \endcode
277  * XQuery function.
278  * This function should not be called directly.
279  * Instead, the \c USER_EXCEPTION macro should be used.
280  *
281  * @param raise_file The C++ source-code file name whence the exception was
282  * raised.
283  * @param raise_line The C++ source-code line number whence the exception was
284  * raised.
285  * @param error The error code expressed as a QName.
286  * @param description The error description.
287  */
288 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_I_S_X
289 make_user_exception( char const *raise_file,
290  ZorbaException::line_type raise_line,
291  Item const &error, String const &description );
292 
293 /**
294  * \internal
295  * Makes a UserException.
296  * This provides for the:
297  * \code
298  * fn:error($error as xs:QName,
299  * $description as xs:string,
300  * $error-object as item()*)
301  * \endcode
302  * XQuery function.
303  * This function should not be called directly.
304  * Instead, the \c USER_EXCEPTION macro should be used.
305  *
306  * @param raise_file The C++ source-code file name whence the exception was
307  * raised.
308  * @param raise_line The C++ source-code line number whence the exception was
309  * raised.
310  * @param error The error code expressed as a QName.
311  * @param description The error description.
312  * @param error_object The error object.
313  */
314 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_I_S_IS_X
315 make_user_exception( char const *raise_file,
316  ZorbaException::line_type raise_line,
317  Item const &error, String const &description,
318  ItemSequence_t const &error_object );
319 
320 /**
321  * \internal
322  * Makes a UserException.
323  * This provides for the:
324  * \code
325  * fn:error($error as xs:QName,
326  * $description as xs:string,
327  * $error-object as item()*)
328  * \endcode
329  * XQuery function.
330  * This function should not be called directly.
331  * Instead, the \c USER_EXCEPTION macro should be used.
332  *
333  * @param raise_file The C++ source-code file name whence the exception was
334  * raised.
335  * @param raise_line The C++ source-code line number whence the exception was
336  * raised.
337  * @param error The error code expressed as a QName.
338  * @param description The error description.
339  * @param error_object The error object.
340  */
341 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_S_IS_X
342 make_user_exception( char const *raise_file,
343  ZorbaException::line_type raise_line,
344  Error const &error, String const &description,
345  ItemSequence_t const &error_object );
346 
347 /**
348  * \internal
349  * Makes a UserException.
350  * This provides for the:
351  * \code
352  * fn:error($error as xs:QName,
353  * $description as xs:string,
354  * $error-object as item()*)
355  * \endcode
356  * XQuery function.
357  * This function should not be called directly.
358  * Instead, the \c USER_EXCEPTION macro should be used.
359  *
360  * @param raise_file The C++ source-code file name whence the exception was
361  * raised.
362  * @param raise_line The C++ source-code line number whence the exception was
363  * raised.
364  * @param error The error code expressed as a QName.
365  * @param description The error description.
366  * @param error_object The error object.
367  */
368 ZORBA_DLL_PUBLIC UserException // MAKE_USER_EXCEPTION_CC_LT_E_S_EOT_X
369 make_user_exception( char const *raise_file,
370  ZorbaException::line_type raise_line,
371  Error const &error, String const &description,
372  error_object_type *error_object = 0 );
373 
374 ///////////////////////////////////////////////////////////////////////////////
375 
376 } // namespace internal
377 } // namespace zorba
378 #endif /* ZORBA_USER_EXCEPTION_API_H */
379 /* vim:set et sw=2 ts=2: */
std::vector< Item > error_object_type
A location holds the file location of an error.
A ZorbaException is the base class for all Zorba exceptions.
internal::error_object_type error_object_type
Diagnostic Error
Definition: error.h:33
An XQueryException is-a ZorbaException for errors with the user's XQuery.
A UserException is-an XQueryException for errors raised via fn:error().
A Diagnostic is the base class for all Zorba diagnostics (errors and warnings).
Definition: diagnostic.h:325
ZORBA_DLL_PUBLIC UserException make_user_exception(char const *raise_file, ZorbaException::line_type raise_line, char const *ns, char const *prefix, char const *localname, char const *description, diagnostic::location const &loc, error_object_type *error_object=0)
zorba::SmartPtr< ItemSequence > ItemSequence_t
internal::diagnostic::location::line_type line_type
void operator&(serialization::Archiver &, const Diagnostic *&)