1 | /* |
2 | * This file is part of Soprano Project. |
3 | * |
4 | * Copyright (C) 2007 Sebastian Trueg <trueg@kde.org> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Library General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Library General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef _SOPRANO_ERROR_H_ |
23 | #define _SOPRANO_ERROR_H_ |
24 | |
25 | #include "soprano_export.h" |
26 | |
27 | #include <QtCore/QString> |
28 | #include <QtCore/QSharedDataPointer> |
29 | |
30 | |
31 | namespace Soprano { |
32 | namespace Error { |
33 | /** |
34 | * %Soprano defines a number of error codes that are |
35 | * used to provide a quick success status check in methods |
36 | * such as Model::addStatement(). |
37 | * |
38 | * \sa Error::Error::code(), Error::convertErrorCode |
39 | */ |
40 | enum ErrorCode { |
41 | ErrorNone = 0x0, /**< No error occurred, i.e. success. */ |
42 | ErrorInvalidArgument = 0x1, /**< Error indicating that a method argument was invalid. For example an invalid Statement in Model::addStatement(). */ |
43 | ErrorInvalidStatement = ErrorInvalidArgument, /**< \deprecated: use ErrorInvalidArgument */ |
44 | ErrorNotSupported = 0x2, /**< Error indicating that a certain functionality is not supported. */ |
45 | ErrorParsingFailed = 0x3, /**< Parsing a query or an RDF serialization failed. */ |
46 | ErrorPermissionDenied = 0x4, /**< Permission is denied. \since 2.1 */ |
47 | ErrorTimeout = 0x5, /**< The command timed out. \since 2.7.4 */ |
48 | ErrorUnknown = 0x1000 /**< An unknown error occurred. */ |
49 | }; |
50 | |
51 | /** |
52 | * Translate an error code into a human-readable error message. |
53 | */ |
54 | SOPRANO_EXPORT QString errorMessage( ErrorCode ); |
55 | |
56 | /** |
57 | * Converts a plain error code (as for example used in Error::code()) |
58 | * into an ErrorCode value. |
59 | * |
60 | * \return \p code converted to ErrorCode. If it is an unknown value, |
61 | * ErrorUnknown will be returned. |
62 | */ |
63 | SOPRANO_EXPORT ErrorCode convertErrorCode( int code ); |
64 | |
65 | class ErrorData; |
66 | class ParserError; |
67 | |
68 | /** |
69 | * \class Error error.h Soprano/Error/Error |
70 | * |
71 | * \brief Represents an error in %Soprano. |
72 | * |
73 | * \author Sebastian Trueg <trueg@kde.org> |
74 | * |
75 | * \sa \ref soprano_error_handling |
76 | */ |
77 | class SOPRANO_EXPORT Error |
78 | { |
79 | public: |
80 | /** |
81 | * Create an Error object, representing success, i.e. no error. |
82 | */ |
83 | Error(); |
84 | |
85 | /** |
86 | * Create an Error object. |
87 | * |
88 | * \param message A human-readable error message. |
89 | * \param code An optional machine-readable error code. Can be one of Soprano::ErrorCode |
90 | * or a user defined value which has to be bigger than ErrorUnknown. The redland backend |
91 | * for example uses error codes <i>ErrorUnknown + redlandCode</i>. |
92 | */ |
93 | Error( const QString& message, int code = ErrorUnknown ); |
94 | |
95 | /** |
96 | * Copy constructor |
97 | */ |
98 | Error( const Error& ); |
99 | |
100 | /** |
101 | * Destructor |
102 | */ |
103 | virtual ~Error(); |
104 | |
105 | Error& operator=( const Error& ); |
106 | |
107 | /** |
108 | * An %Error evaluates to a boolean, indicating if an %Error is "set". |
109 | * |
110 | * \return \p false if code() == #ErrorNone, \p true otherwise. |
111 | * |
112 | * Thus, an Error object can easily be checked as follows: |
113 | * |
114 | * \code |
115 | * model.addStatement( s ); |
116 | * if( model.lastError() ) { |
117 | * displayError( model.lastError() ); |
118 | * } |
119 | * \endcode |
120 | */ |
121 | operator bool() const { return code() != ErrorNone; } |
122 | |
123 | /** |
124 | * A string explaining the error in detail. |
125 | * This string is not necessarily translated (this |
126 | * depends on the plugin implementation). |
127 | * |
128 | * \return An error message describing the error or an empty string |
129 | * for no-error (i.e. success) instances. |
130 | */ |
131 | QString message() const; |
132 | |
133 | /** |
134 | * An error code. If the error code is #ErrorNone the |
135 | * Error instance represents success. |
136 | * The code can either be one of the values of ErrorCode |
137 | * or a value above #ErrorUnknown. |
138 | * |
139 | * Example: The redland backend defines the error code |
140 | * as: |
141 | * \code |
142 | * ErrorUnknown + librdf_log_message_code() |
143 | * \endcode |
144 | * |
145 | * \sa ErrorCode, Error::convertErrorCode |
146 | */ |
147 | int code() const; |
148 | |
149 | /** |
150 | * \return \p true if this Error instance represents a parser error. |
151 | * In that case the error can be converted to a ParserError. |
152 | */ |
153 | bool isParserError() const; |
154 | |
155 | /** |
156 | * Converts this error into a ParserError. |
157 | * This has the same effect as |
158 | * \code |
159 | * Error e; |
160 | * ParserError p1( e ); |
161 | * \endcode |
162 | * |
163 | * \return If isParserError() returns true a ParserError |
164 | * with a valid Locator value, otherwise a ParserError with |
165 | * an empty Locator. |
166 | */ |
167 | ParserError toParserError() const; |
168 | |
169 | protected: |
170 | /** \cond protected_error_members */ |
171 | Error( ErrorData* ); |
172 | QSharedDataPointer<ErrorData> d; |
173 | /** \endcond */ |
174 | }; |
175 | |
176 | class Locator; |
177 | |
178 | /** |
179 | * \class ParserError error.h Soprano/Error/ParserError |
180 | * |
181 | * \brief Represents a parser error in %Soprano. |
182 | * |
183 | * ParserError represents an error during parsing of either a query string (Soprano::Query::Parser::parseQuery()) |
184 | * or an RDF serialization (Soprano::Parser::parseStream()). |
185 | * Error and ParserError can be used together and copied without loosing information. |
186 | * |
187 | * The following code is perfectly valid and works: |
188 | * |
189 | * \code |
190 | * ParserError pe( 3, 4 ); |
191 | * Error e = pe; |
192 | * ParserError otherPe = e; |
193 | * qDebug() << "Parsing failed at line " << otherPe.line() << " and column " << otherPe.column(); |
194 | * \endcode |
195 | * |
196 | * \author Sebastian Trueg <trueg@kde.org> |
197 | * |
198 | * \sa \ref soprano_error_handling |
199 | */ |
200 | class SOPRANO_EXPORT ParserError : public Error |
201 | { |
202 | public: |
203 | /** |
204 | * Create an Error object, representing success, i.e. no error. |
205 | */ |
206 | ParserError(); |
207 | |
208 | ParserError( const Locator&, const QString& message = QString(), int code = ErrorParsingFailed ); |
209 | |
210 | ParserError( const Error& ); |
211 | |
212 | ~ParserError(); |
213 | |
214 | ParserError& operator=( const Error& ); |
215 | |
216 | Locator locator() const; |
217 | }; |
218 | |
219 | /** |
220 | * \class ErrorCache error.h Soprano/Error/ErrorCache |
221 | * |
222 | * \brief Core class of %Soprano's exception system. |
223 | * |
224 | * The ErrorCache caches Error instances for different threads. |
225 | * Each thread has its own last error. This mechanism tries to |
226 | * replace the missing exceptions for methods that do not return |
227 | * an error code or another value that can state the success of the |
228 | * method's operation. |
229 | * |
230 | * \author Sebastian Trueg <trueg@kde.org> |
231 | * |
232 | * \sa \ref soprano_error_handling |
233 | */ |
234 | class SOPRANO_EXPORT ErrorCache |
235 | { |
236 | public: |
237 | virtual ~ErrorCache(); |
238 | |
239 | /** |
240 | * Get the last error that occurred in the current thread. |
241 | */ |
242 | virtual Error lastError() const; |
243 | |
244 | protected: |
245 | ErrorCache(); |
246 | |
247 | /** |
248 | * Reset the error for the current thread to no error. |
249 | */ |
250 | void clearError() const; |
251 | |
252 | /** |
253 | * Set the last occurred error. This method is const to allow setting |
254 | * of errors in all types of methods. The last error is as such a |
255 | * mutable property. |
256 | */ |
257 | void setError( const Error& ) const; |
258 | |
259 | /** |
260 | * Convenience method to set simple string error messages with a default |
261 | * error code ErrorUnknown. |
262 | */ |
263 | void setError( const QString& errorMessage, int code = ErrorUnknown ) const; |
264 | |
265 | private: |
266 | class Private; |
267 | Private* const d; |
268 | }; |
269 | } |
270 | } |
271 | |
272 | class QDebug; |
273 | class QTextStream; |
274 | |
275 | SOPRANO_EXPORT QDebug operator<<( QDebug s, const Soprano::Error::Error& ); |
276 | SOPRANO_EXPORT QTextStream& operator<<( QTextStream& s, const Soprano::Error::Error& ); |
277 | |
278 | #endif |
279 | |