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