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