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
31namespace 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
272class QDebug;
273class QTextStream;
274
275SOPRANO_EXPORT QDebug operator<<( QDebug s, const Soprano::Error::Error& );
276SOPRANO_EXPORT QTextStream& operator<<( QTextStream& s, const Soprano::Error::Error& );
277
278#endif
279