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