Line data Source code
1 : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : /*
3 : * This file is part of the LibreOffice project.
4 : *
5 : * This Source Code Form is subject to the terms of the Mozilla Public
6 : * License, v. 2.0. If a copy of the MPL was not distributed with this
7 : * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 : *
9 : * This file incorporates work covered by the following license notice:
10 : *
11 : * Licensed to the Apache Software Foundation (ASF) under one or more
12 : * contributor license agreements. See the NOTICE file distributed
13 : * with this work for additional information regarding copyright
14 : * ownership. The ASF licenses this file to you under the Apache
15 : * License, Version 2.0 (the "License"); you may not use this file
16 : * except in compliance with the License. You may obtain a copy of
17 : * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18 : */
19 :
20 : #ifndef INCLUDED_CONNECTIVITY_SQLERROR_HXX
21 : #define INCLUDED_CONNECTIVITY_SQLERROR_HXX
22 :
23 : #include <com/sun/star/sdbc/SQLException.hpp>
24 : #include <com/sun/star/uno/XComponentContext.hpp>
25 :
26 : #include <boost/shared_ptr.hpp>
27 : #include <boost/optional.hpp>
28 : #include <connectivity/dbtoolsdllapi.hxx>
29 :
30 :
31 : namespace connectivity
32 : {
33 :
34 :
35 :
36 : //= ErrorCondition
37 :
38 : /** the type of error codes to be used in SQLExceptions
39 :
40 : @see com::sun::star::sdbc::SQLException::ErrorCode
41 : */
42 : typedef ::sal_Int32 ErrorCode;
43 :
44 : /** error condition values as defined in com::sun::star::sdb::ErrorCondition
45 : */
46 : typedef ::sal_Int32 ErrorCondition;
47 :
48 :
49 : //= SQLError
50 :
51 : class SQLError_Impl;
52 :
53 : /** a class which provides helpers for working with SQLErrors
54 :
55 : In particular, this class provides vendor-specific error codes (where
56 : the vendor is OpenOffice.org Base), which can be used in OOo's various
57 : database drivers, and checked in application-level code, to properly
58 : recognize highly specific error conditions.
59 :
60 : @see ::com::sun::star::sdb::ErrorCondition
61 : */
62 : class OOO_DLLPUBLIC_DBTOOLS SQLError
63 : {
64 : public:
65 :
66 : // - optional
67 :
68 : /** convenience wrapper around boost::optional, allowing implicit construction
69 : */
70 0 : class ParamValue : public ::boost::optional< OUString >
71 : {
72 : typedef ::boost::optional< OUString > base_type;
73 :
74 : public:
75 0 : ParamValue( ) : base_type( ) { }
76 0 : ParamValue( OUString const& val ) : base_type( val ) { }
77 0 : ParamValue( ParamValue const& rhs ) : base_type( (base_type const&)rhs ) { }
78 :
79 0 : bool is() const { return !base_type::operator!(); }
80 : };
81 :
82 :
83 : public:
84 : explicit SQLError( const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext > & _rxContext );
85 : ~SQLError();
86 :
87 : /** returns the message associated with a given error condition, after (optionally) replacing
88 : a placeholder with a given string
89 :
90 : Some error messages need to contain references to runtime-dependent data (say, the
91 : name of a concrete table in the database), which in the resource file's strings are
92 : represented by a placeholder, namely $1$, $2, and so on. This method allows to
93 : retrieve such an error message, and replace upo to 3 placeholders with their concrete
94 : values.
95 :
96 : In a non-product build, assertions will fire if the number of placeholders in the
97 : message's resource string does not match the number of passed parameter values.
98 :
99 : As specified in the com::sun::star::sdb::ErrorCondition type,
100 : error messages thrown by core components of OpenOffice.org Base will contain
101 : a standardized prefix "[OOoBase]" in every message.
102 :
103 : @param _rParamValue1
104 : the value which the placeholder $1$ should be replaced with. If this value is
105 : not present (see <code>::boost::optional::operator !</code>), then no replacement
106 : will happen, and <code>_rParamValue2</code> and <code>_rParamValue3</code> will be
107 : ignored.
108 :
109 : @param _rParamValue2
110 : the value which the placeholder $2$ should be replaced with. If this value is
111 : not present (see <code>::boost::optional::operator !</code>), then no replacement
112 : will happen, and <code>_rParamValue3</code> will be ignored.
113 :
114 : @param _rParamValue1
115 : the value which the placeholder $1$ should be replaced with. If this value is
116 : not present (see <code>::boost::optional::operator !</code>), then no replacement
117 : will happen.
118 :
119 : @see ::com::sun::star::sdb::ErrorCondition
120 : */
121 : OUString getErrorMessage(
122 : const ErrorCondition _eCondition,
123 : const ParamValue& _rParamValue1 = ParamValue(),
124 : const ParamValue& _rParamValue2 = ParamValue(),
125 : const ParamValue& _rParamValue3 = ParamValue()
126 : ) const;
127 :
128 : /** returns the error code associated with a given error condition
129 :
130 : @see getErrorMessage
131 : @see ::com::sun::star::sdb::ErrorCondition
132 : @see ::com::sun::star::sdbc::SQLException::ErrorCode
133 : */
134 : static ErrorCode
135 : getErrorCode( const ErrorCondition _eCondition );
136 :
137 : /** returns the prefix which is used for OpenOffice.org Base's error messages
138 :
139 : As specified in the com::sun::star::sdb::ErrorCondition type,
140 : error messages thrown by core components of OpenOffice.org Base will
141 : contain a standardized prefix in every message. <code>getBaseErrorMessagePrefix</code>
142 : returns this prefix, so clients of such error messages might decide to strip this
143 : prefix before presenting the message to the user, or use it to determine
144 : whether a concrete error has been raised by a OpenOffice.org core component.
145 : */
146 : static const OUString&
147 : getMessagePrefix();
148 :
149 :
150 : /** throws an SQLException describing the given error condition
151 :
152 : The thrown SQLException will contain the OOo-specific error code which derives
153 : from the given error condition, and the error message associated with that condition.
154 :
155 : @param _eCondition
156 : the ErrorCondition which hit you
157 :
158 : @param _rxContext
159 : the context in which the error occurred. This will be filled in as
160 : <member scope="com::sun::star::uno">Exception::Context</member> member.
161 :
162 : @param _rParamValue1
163 : a runtime-dependent value which should be filled into the error message
164 : which is associated with <arg>_eCondition</arg>, replacing the first placeholder
165 : in this message.
166 :
167 : @param _rParamValue2
168 : a runtime-dependent value which should be filled into the error message
169 : which is associated with <arg>_eCondition</arg>, replacing the second placeholder
170 : in this message.
171 :
172 : @param _rParamValue3
173 : a runtime-dependent value which should be filled into the error message
174 : which is associated with <arg>_eCondition</arg>, replacing the third placeholder
175 : in this message.
176 :
177 : @see getErrorMessage
178 : @see getErrorCode
179 : */
180 : void raiseException(
181 : const ErrorCondition _eCondition,
182 : const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
183 : const ParamValue& _rParamValue1 = ParamValue(),
184 : const ParamValue& _rParamValue2 = ParamValue(),
185 : const ParamValue& _rParamValue3 = ParamValue()
186 : ) const;
187 :
188 : /** throws an SQLException describing the given error condition
189 :
190 : The thrown SQLException will contain the OOo-specific error code which derives
191 : from the given error condition, and the error message associated with that condition.
192 :
193 : Note: You should prefer the version of raiseException which takes
194 : an additional Context parameter, since this allows clients of your
195 : exception to examine where the error occurred.
196 :
197 : @param _eCondition
198 : the ErrorCondition which hit you
199 :
200 : @param _rParamValue1
201 : a runtime-dependent value which should be filled into the error message
202 : which is associated with <arg>_eCondition</arg>, replacing the first placeholder
203 : in this message.
204 :
205 : @param _rParamValue2
206 : a runtime-dependent value which should be filled into the error message
207 : which is associated with <arg>_eCondition</arg>, replacing the second placeholder
208 : in this message.
209 :
210 : @param _rParamValue3
211 : a runtime-dependent value which should be filled into the error message
212 : which is associated with <arg>_eCondition</arg>, replacing the third placeholder
213 : in this message.
214 :
215 : @see getErrorMessage
216 : @see getErrorCode
217 : */
218 : void raiseException(
219 : const ErrorCondition _eCondition,
220 : const ParamValue& _rParamValue1 = ParamValue(),
221 : const ParamValue& _rParamValue2 = ParamValue(),
222 : const ParamValue& _rParamValue3 = ParamValue()
223 : ) const;
224 :
225 : /** raises a typed exception, that is, a UNO exception which is derived from
226 : com::sun::star::sdbc::SQLException
227 :
228 : @param _eCondition
229 : the ErrorCondition which hit you
230 :
231 : @param _rxContext
232 : the context in which the error occurred. This will be filled in as
233 : <member scope="com::sun::star::uno">Exception::Context</member> member.
234 :
235 : @param _rExceptionType
236 : the type of the exception to throw. This type <em>must</em> specify
237 : an exception class derived from com::sun::star::sdbc::SQLException.
238 :
239 : @param _rParamValue1
240 : a runtime-dependent value which should be filled into the error message
241 : which is associated with <arg>_eCondition</arg>, replacing the first placeholder
242 : in this message.
243 :
244 : @param _rParamValue2
245 : a runtime-dependent value which should be filled into the error message
246 : which is associated with <arg>_eCondition</arg>, replacing the second placeholder
247 : in this message.
248 :
249 : @param _rParamValue3
250 : a runtime-dependent value which should be filled into the error message
251 : which is associated with <arg>_eCondition</arg>, replacing the third placeholder
252 : in this message.
253 :
254 : @throws ::std::bad_cast
255 : if <arg>_rExceptionType</arg> does not specify an exception class derived from
256 : com::sun::star::sdbc::SQLException.
257 :
258 : @see getErrorMessage
259 : @see getErrorCode
260 : */
261 : void raiseTypedException(
262 : const ErrorCondition _eCondition,
263 : const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
264 : const ::com::sun::star::uno::Type& _rExceptionType,
265 : const ParamValue& _rParamValue1 = ParamValue(),
266 : const ParamValue& _rParamValue2 = ParamValue(),
267 : const ParamValue& _rParamValue3 = ParamValue()
268 : ) const;
269 :
270 : /** retrieves an <code>SQLException</code> object which contains information about
271 : the given error condition
272 :
273 : @param _eCondition
274 : the ErrorCondition which hit you
275 :
276 : @param _rxContext
277 : the context in which the error occurred. This will be filled in as
278 : <member scope="com::sun::star::uno">Exception::Context</member> member.
279 :
280 : @param _rParamValue1
281 : a runtime-dependent value which should be filled into the error message
282 : which is associated with <arg>_eCondition</arg>, replacing the first placeholder
283 : in this message.
284 :
285 : @param _rParamValue2
286 : a runtime-dependent value which should be filled into the error message
287 : which is associated with <arg>_eCondition</arg>, replacing the second placeholder
288 : in this message.
289 :
290 : @param _rParamValue3
291 : a runtime-dependent value which should be filled into the error message
292 : which is associated with <arg>_eCondition</arg>, replacing the third placeholder
293 : in this message.
294 :
295 : @see getErrorMessage
296 : @see getErrorCode
297 : */
298 : ::com::sun::star::sdbc::SQLException
299 : getSQLException(
300 : const ErrorCondition _eCondition,
301 : const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
302 : const ParamValue& _rParamValue1 = ParamValue(),
303 : const ParamValue& _rParamValue2 = ParamValue(),
304 : const ParamValue& _rParamValue3 = ParamValue()
305 : ) const;
306 :
307 : private:
308 : ::boost::shared_ptr< SQLError_Impl > m_pImpl;
309 : };
310 :
311 :
312 : } // namespace connectivity
313 :
314 :
315 : #endif // INCLUDED_CONNECTIVITY_SQLERROR_HXX
316 :
317 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
