xquery_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_XQUERY_EXCEPTION_API_H
18 #define ZORBA_XQUERY_EXCEPTION_API_H
19 
21 #include <zorba/zorba_exception.h>
22 
23 namespace zorba {
24 
25 namespace serialization {
26  class Archiver;
27  void operator&( Archiver&, ZorbaException*& );
28 }
29 
30 ///////////////////////////////////////////////////////////////////////////////
31 
32 /**
33  * An %XQueryException is-a ZorbaException for errors with the user's XQuery.
34  * An %XQueryException therefore also contains the XQuery source URI, line, and
35  * column numbers.
36  */
37 class ZORBA_DLL_PUBLIC XQueryException : public ZorbaException {
38 public:
40 
41  /**
42  * Whether to include the XQuery stack trace for the XQueryException that's
43  * printed to an ostream.
44  */
45  enum print_trace {
47  no_trace
48  };
49 
50  /**
51  * Copy-constructs an %XQueryException.
52  *
53  * @param from The %XQueryException to copy from.
54  */
55  XQueryException( XQueryException const &from );
56 
57  /**
58  * Destroys this %XQueryException.
59  */
60  ~XQueryException() throw();
61 
62  /**
63  * Assigns this %XQueryException from another.
64  *
65  * @param from The %XQueryException to assign from.
66  * @return Returns \c *this.
67  */
68  XQueryException& operator=( XQueryException const &from );
69 
70  ////////// source file/line location ////////////////////////////////////////
71 
72  /**
73  * Checks whether the XQuery source-code location has been set.
74  *
75  * @return Returns \c true only if said has been set.
76  */
77  bool has_source() const throw() {
78  return source_loc_;
79  }
80 
81  /**
82  * Sets the XQuery source-code URI name, line, and column numbers.
83  *
84  * @param uri The source-code URI name.
85  * @param line The source-code URI line number.
86  * @param column The source-code URI column number.
87  * @param line_end The source-code URI end line number.
88  * @param column_end The source-code URI end column number.
89  */
90  void set_source( char const *uri,
91  line_type line,
92  column_type column = 0,
93  line_type line_end = 0,
94  column_type column_end = 0 );
95 
96  /**
97  * Gets the XQuery source-code URI containing the error.
98  *
99  * @return Returns said URI or the empty string if unset.
100  */
101  char const* source_uri() const throw() {
102  return source_loc_.file();
103  }
104 
105  /**
106  * Gets the XQuery source-code line number containing the error.
107  *
108  * @return Returns said line number or 0 if unset.
109  */
110  line_type source_line() const throw() {
111  return source_loc_.line();
112  }
113 
114  /**
115  * Gets the XQuery source-code column number containing the error.
116  *
117  * @return Returns said column number or 0 if unset.
118  */
119  column_type source_column() const throw() {
120  return source_loc_.column();
121  }
122 
123  /**
124  * Gets the XQuery source-code end line number containing the error.
125  *
126  * @return Returns said line number or 0 if unset.
127  */
128  line_type source_line_end() const throw() {
129  return source_loc_.line_end();
130  }
131 
132  /**
133  * Gets the XQuery source-code end column number containing the error.
134  *
135  * @return Returns said column number or 0 if unset.
136  */
137  column_type source_column_end() const throw() {
138  return source_loc_.column_end();
139  }
140 
141  ////////// data file/line location //////////////////////////////////////////
142 
143  /**
144  * Checks whether the XQuery data location has been set.
145  *
146  * @return Returns \c true only if the data location has been set.
147  */
148  bool has_data() const throw() {
149  return data_loc_;
150  }
151 
152  /**
153  * Sets the XQuery source-code data URI name, line, and column numbers.
154  *
155  * @param uri The source-code data URI name. Must not be null.
156  * @param line The source-code data URI line number.
157  * @param column The source-code data URI column number.
158  * @param line_end The source-code data URI end line number.
159  * @param column_end The source-code data URI end column number.
160  */
161  void set_data( char const *uri,
162  line_type line,
163  column_type column = 0,
164  line_type line_end = 0,
165  column_type column_end = 0 );
166 
167  /**
168  * Gets the data URI containing the error.
169  *
170  * @return Returns said URI or the empty string if unset.
171  */
172  char const* data_uri() const throw() {
173  return data_loc_.file();
174  }
175 
176  /**
177  * Gets the data line number containing the error.
178  *
179  * @return Returns said line number or 0 if unset.
180  */
181  line_type data_line() const throw() {
182  return data_loc_.line();
183  }
184 
185  /**
186  * Gets the data column number containing the error.
187  *
188  * @return Returns said column number or 0 if unset.
189  */
190  column_type data_column() const throw() {
191  return data_loc_.column();
192  }
193 
194  /**
195  * Gets the data end line number containing the error.
196  *
197  * @return Returns said line number or 0 if unset.
198  */
199  line_type data_line_end() const throw() {
200  return data_loc_.line_end();
201  }
202 
203  /**
204  * Gets the data end column number containing the error.
205  *
206  * @return Returns said column number or 0 if unset.
207  */
208  column_type data_column_end() const throw() {
209  return data_loc_.column_end();
210  }
211 
212  ////////// "applied at" file/line location //////////////////////////////////
213 
214  /**
215  * Checks whether the XQuery "applied at" location has been set.
216  *
217  * @return Returns \c true only if the "applied at" location has been set.
218  */
219  bool has_applied() const throw() {
220  return applied_loc_;
221  }
222 
223  /**
224  * Sets the XQuery source-code "applied at" URI name, line, and column
225  * numbers.
226  *
227  * @param uri The source-code "applied at" URI name. If either the null
228  * pointer or the empty string, \c source_uri() is used.
229  * @param line The source-code "applied at" URI line number.
230  * @param column The source-code "applied at" URI column number.
231  * @param line_end The source-code "applied at" URI end line number.
232  * @param column_end The source-code "applied at" URI end column number.
233  */
234  void set_applied( char const *uri,
235  line_type line,
236  column_type column = 0,
237  line_type line_end = 0,
238  column_type column_end = 0 );
239 
240  /**
241  * Gets the XQuery source-code "applied at" URI containing the error.
242  *
243  * @return Returns said URI or the empty string if unset.
244  */
245  char const* applied_uri() const throw() {
246  return applied_loc_.file();
247  }
248 
249  /**
250  * Gets the XQuery source-code "applied at" line number containing the error.
251  *
252  * @return Returns said line number or 0 if unset.
253  */
254  line_type applied_line() const throw() {
255  return applied_loc_.line();
256  }
257 
258  /**
259  * Gets the XQuery source-code "applied at" column number containing the
260  * error.
261  *
262  * @return Returns said column number or 0 if unset.
263  */
264  column_type applied_column() const throw() {
265  return applied_loc_.column();
266  }
267 
268  /**
269  * Gets the XQuery source-code "applied at" end line number containing the
270  * error.
271  *
272  * @return Returns said line number or 0 if unset.
273  */
274  line_type applied_line_end() const throw() {
275  return applied_loc_.line_end();
276  }
277 
278  /**
279  * Gets the XQuery source-code "applied at" end column number containing the
280  * error.
281  *
282  * @return Returns said column number or 0 if unset.
283  */
284  column_type applied_column_end() const throw() {
285  return applied_loc_.column_end();
286  }
287 
288  ////////// XQuery stack trace ///////////////////////////////////////////////
289 
290  /**
291  * Gets whether XQuery stack traces will be included when XQueryExceptions
292  * are printed to the given ostream.
293  *
294  * @param o The ostream.
295  * @return Returns \a true only if stack traces will be included.
296  */
297  static bool get_print_trace( std::ostream &o ) {
298  return !!( o.iword( get_ios_trace_index() ) );
299  }
300 
301  /**
302  * Gets the XQuery stack trace, if any.
303  *
304  * @return Returns said stack trace.
305  */
307  return query_trace_;
308  }
309 
310  /**
311  * Gets the XQuery stack trace, if any.
312  *
313  * @return Returns said stack trace.
314  */
315  XQueryStackTrace const& query_trace() const throw() {
316  return query_trace_;
317  }
318 
319  /**
320  * Sets whether XQuery stack traces will be included when XQueryExceptions
321  * are printed to the given ostream.
322  *
323  * @param o The ostream to affect.
324  * @param print If \a true, stack traces will be included.
325  */
326  static void set_print_trace( std::ostream &o, bool print ) {
327  o.iword( get_ios_trace_index() ) = print;
328  }
329 
330  /////////////////////////////////////////////////////////////////////////////
331 
332  // inherited
333  void polymorphic_throw() const;
334 
335 protected:
336  std::ostream& print_stack_trace( std::ostream& ) const;
337  static bool print_uri( std::ostream&, char const *uri );
338 
339  // inherited
340  std::unique_ptr<ZorbaException> clone() const;
341  std::ostream& print_impl( std::ostream& ) const;
342 
343 private:
344  typedef internal::diagnostic::location location;
345  typedef internal::diagnostic::parameters parameters;
346 
347  /**
348  * Constructs an %XQueryException.
349  *
350  * @param diagnostic The diagnostic.
351  * @param raise_file The C++ source-code file name whence the exception was
352  * raised.
353  * @param raise_line The C++ source-code line number whence the exception was
354  * raised.
355  * @param message The diagnostic message.
356  */
357  XQueryException( Diagnostic const &diagnostic, char const *raise_file,
358  line_type raise_line, char const *message );
359 
360  location source_loc_;
361  location data_loc_;
362  location applied_loc_;
363  XQueryStackTrace query_trace_;
364 
365  static int get_ios_trace_index();
366 
367  friend XQueryException make_xquery_exception(
368  char const*, ZorbaException::line_type, Diagnostic const&,
369  parameters const&, location const&
370  );
371 
372  friend XQueryException* new_xquery_exception(
373  char const*, ZorbaException::line_type, Diagnostic const&,
374  parameters const&, location const&
375  );
376 
377  friend void set_applied( ZorbaException&, char const*, line_type, column_type,
378  line_type, column_type, bool );
379 
380  friend void set_data( ZorbaException&, char const*, line_type, column_type,
381  line_type, column_type, bool );
382 
383  friend void set_source( ZorbaException&, char const*, line_type, column_type,
384  line_type, column_type, bool );
385 
386  friend class UserException;
387 
388 protected:
389  // for plan serialization
390  XQueryException( serialization::Archiver &ar );
391  friend void serialization::operator&( serialization::Archiver&,
392  ZorbaException*& );
393 };
394 
395 ///////////////////////////////////////////////////////////////////////////////
396 
397 /**
398  * Sets whether to include the XQuery stack trace for the next XQueryException
399  * that's printed.
400  *
401  * @param o The ostream to affect.
402  * @param t The print_trace value.
403  * @return Returns \a o.
404  */
405 inline std::ostream& operator<<( std::ostream &o,
408  return o;
409 }
410 
411 ///////////////////////////////////////////////////////////////////////////////
412 
413 } // namespace zorba
414 #endif /* ZORBA_XQUERY_EXCEPTION_API_H */
415 /* vim:set et sw=2 ts=2: */
static void set_print_trace(std::ostream &o, bool print)
Sets whether XQuery stack traces will be included when XQueryExceptions are printed to the given ostr...
char const * applied_uri() const
Gets the XQuery source-code "applied at" URI containing the error.
A location holds the file location of an error.
A ZorbaException is the base class for all Zorba exceptions.
line_type applied_line() const
Gets the XQuery source-code "applied at" line number containing the error.
column_type applied_column_end() const
Gets the XQuery source-code "applied at" end column number containing the error.
XQueryStackTrace & query_trace()
Gets the XQuery stack trace, if any.
unsigned short column_type
The column-number type.
line_type data_line_end() const
Gets the data end line number containing the error.
An XQueryException is-a ZorbaException for errors with the user's XQuery.
bool has_data() const
Checks whether the XQuery data location has been set.
line_type source_line() const
Gets the XQuery source-code line number containing the error.
line_type source_line_end() const
Gets the XQuery source-code end line number containing the error.
A UserException is-an XQueryException for errors raised via fn:error().
char const * source_uri() const
Gets the XQuery source-code URI containing the error.
A Diagnostic is the base class for all Zorba diagnostics (errors and warnings).
Definition: diagnostic.h:325
column_type data_column() const
Gets the data column number containing the error.
line_type applied_line_end() const
Gets the XQuery source-code "applied at" end line number containing the error.
column_type data_column_end() const
Gets the data end column number containing the error.
internal::diagnostic::location::column_type column_type
bool has_applied() const
Checks whether the XQuery "applied at" location has been set.
static bool get_print_trace(std::ostream &o)
Gets whether XQuery stack traces will be included when XQueryExceptions are printed to the given ostr...
column_type source_column() const
Gets the XQuery source-code column number containing the error.
internal::diagnostic::location::line_type line_type
char const * data_uri() const
Gets the data URI containing the error.
print_trace
Whether to include the XQuery stack trace for the XQueryException that's printed to an ostream...
ZORBA_DLL_PUBLIC std::ostream & operator<<(std::ostream &os, const QueryLocation &aQuery)
void operator&(serialization::Archiver &, const Diagnostic *&)
XQueryStackTrace const & query_trace() const
Gets the XQuery stack trace, if any.
column_type source_column_end() const
Gets the XQuery source-code end column number containing the error.
column_type applied_column() const
Gets the XQuery source-code "applied at" column number containing the error.
line_type data_line() const
Gets the data line number containing the error.