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 _DBHELPER_DBEXCEPTION_HXX_ 25 #define _DBHELPER_DBEXCEPTION_HXX_ 26 27 #include <com/sun/star/sdbc/SQLException.hpp> 28 #include "connectivity/standardsqlstate.hxx" 29 #include "connectivity/dbtoolsdllapi.hxx" 30 31 namespace com 32 { 33 namespace sun 34 { 35 namespace star 36 { 37 namespace sdb 38 { 39 class SQLContext; 40 struct SQLErrorEvent; 41 } 42 namespace sdbc 43 { 44 class SQLWarning; 45 } 46 } 47 } 48 } 49 //......................................................................... 50 namespace dbtools 51 { 52 //......................................................................... 53 54 //============================================================================== 55 //= Special exception if cancel is pressed in DBA UI 56 //============================================================================== 57 enum OOoBaseErrorCode 58 { 59 ParameterInteractionCancelled = 1 60 }; 61 62 //============================================================================== 63 //= SQLExceptionInfo - encapsulating the type info of an SQLException-derived class 64 //============================================================================== 65 66 class OOO_DLLPUBLIC_DBTOOLS SQLExceptionInfo 67 { 68 public: 69 enum TYPE { SQL_EXCEPTION, SQL_WARNING, SQL_CONTEXT, UNDEFINED }; 70 71 private: 72 ::com::sun::star::uno::Any m_aContent; 73 TYPE m_eType; // redundant (could be derived from m_aContent.getValueType()) 74 75 public: 76 SQLExceptionInfo(); 77 SQLExceptionInfo(const ::com::sun::star::sdbc::SQLException& _rError); 78 SQLExceptionInfo(const ::com::sun::star::sdbc::SQLWarning& _rError); 79 SQLExceptionInfo(const ::com::sun::star::sdb::SQLContext& _rError); 80 81 /** convenience constructor 82 83 If your error processing relies on SQLExceptions, and SQLExceptionInfos, you still may 84 need to display an error which consists of a simple message string only. 85 In those cases, you can use this constructor, which behaves as if you would have used 86 an SQLException containing exactly the given error message. 87 */ 88 SQLExceptionInfo( const ::rtl::OUString& _rSimpleErrorMessage ); 89 90 SQLExceptionInfo(const SQLExceptionInfo& _rCopySource); 91 92 SQLExceptionInfo(const ::com::sun::star::sdb::SQLErrorEvent& _rError); 93 // use for events got via XSQLErrorListener::errorOccured 94 SQLExceptionInfo(const ::com::sun::star::uno::Any& _rError); 95 // use with the Reason member of an SQLErrorEvent or with NextElement of an SQLException 96 97 /** prepends a plain error message to the chain of exceptions 98 @param _rSimpleErrorMessage 99 the error message to prepend 100 @param _pAsciiSQLState 101 the SQLState of the to-be-constructed SQLException, or NULL if this should be defaulted to HY000 102 @param _nErrorCode 103 the ErrorCode of the to-be-constructed SQLException 104 */ 105 void prepend( const ::rtl::OUString& _rErrorMessage, const sal_Char* _pAsciiSQLState = NULL, const sal_Int32 _nErrorCode = 0 ); 106 107 /** appends a plain message to the chain of exceptions 108 @param _eType 109 the type of exception to append. Must be SQL_EXCEPTION, SQL_WARNING, SQL_CONTEXT, for all other 110 values, the behavior is undefined. 111 @param _rErrorMessage 112 the message to append 113 @param _pAsciiSQLState 114 the SQLState of the exception to append 115 @param _nErrorCode 116 the error code of the exception to append 117 */ 118 void append( TYPE _eType, const ::rtl::OUString& _rErrorMessage, const sal_Char* _pAsciiSQLState = NULL, const sal_Int32 _nErrorCode = 0 ); 119 120 /** throws (properly typed) the exception contained in the object 121 @precond 122 isValid() returns <TRUE/> 123 @throws SQLException 124 @throws RuntimeException 125 if the instance does not contain an SQLException 126 */ 127 void doThrow(); 128 129 const SQLExceptionInfo& operator=(const ::com::sun::star::sdbc::SQLException& _rError); 130 const SQLExceptionInfo& operator=(const ::com::sun::star::sdbc::SQLWarning& _rError); 131 const SQLExceptionInfo& operator=(const ::com::sun::star::sdb::SQLContext& _rError); 132 const SQLExceptionInfo& operator=(const ::com::sun::star::sdb::SQLErrorEvent& _rErrorEvent); 133 const SQLExceptionInfo& operator=(const ::com::sun::star::uno::Any& _rCaughtSQLException); 134 135 sal_Bool isKindOf(TYPE _eType) const; 136 // not just a simple comparisation ! e.g. getType() == SQL_CONTEXT implies isKindOf(SQL_EXCEPTION) == sal_True ! isValid() const137 sal_Bool isValid() const { return m_eType != UNDEFINED; } getType() const138 TYPE getType() const { return m_eType; } 139 140 operator const ::com::sun::star::sdbc::SQLException* () const; 141 operator const ::com::sun::star::sdbc::SQLWarning* () const; 142 operator const ::com::sun::star::sdb::SQLContext* () const; 143 get() const144 const ::com::sun::star::uno::Any& get() const { return m_aContent; } 145 clear()146 void clear() 147 { 148 m_aContent.clear(); 149 m_eType = UNDEFINED; 150 } 151 152 protected: 153 void implDetermineType(); 154 }; 155 156 //============================================================================== 157 //= SQLExceptionIteratorHelper - iterating through an SQLException chain 158 //============================================================================== 159 160 class OOO_DLLPUBLIC_DBTOOLS SQLExceptionIteratorHelper 161 { 162 protected: 163 const ::com::sun::star::sdbc::SQLException* m_pCurrent; 164 SQLExceptionInfo::TYPE m_eCurrentType; 165 166 public: 167 /** constructs an iterator instance from an SQLException 168 169 @param _rChainStart 170 the start of the exception chain to iterate. Must live as long as the iterator 171 instances lives, at least. 172 */ 173 SQLExceptionIteratorHelper( const ::com::sun::star::sdbc::SQLException& _rChainStart ); 174 175 /** constructs an iterator instance from an SQLWarning 176 177 @param _rChainStart 178 the start of the exception chain to iterate. Must live as long as the iterator 179 instances lives, at least. 180 */ 181 SQLExceptionIteratorHelper( const ::com::sun::star::sdbc::SQLWarning& _rChainStart ); 182 183 /** constructs an iterator instance from an SQLContext 184 185 @param _rChainStart 186 the start of the exception chain to iterate. Must live as long as the iterator 187 instances lives, at least. 188 */ 189 SQLExceptionIteratorHelper( const ::com::sun::star::sdb::SQLContext& _rChainStart ); 190 191 /** constructs an iterator instance from an SQLExceptionInfo 192 193 @param _rErrorInfo 194 the start of the exception chain to iterate. Must live as long as the iterator 195 instances lives, at least. 196 */ 197 SQLExceptionIteratorHelper( const SQLExceptionInfo& _rErrorInfo ); 198 199 /** determines whether there are more elements in the exception chain 200 */ hasMoreElements() const201 sal_Bool hasMoreElements() const { return ( m_pCurrent != NULL ); } 202 203 /** returns the type of the current element in the exception chain 204 */ currentType() const205 SQLExceptionInfo::TYPE currentType() const { return m_eCurrentType; } 206 207 /** retrieves the current element in the chain, or <NULL/> if the chain has been completely 208 traveled. 209 */ current() const210 const ::com::sun::star::sdbc::SQLException* current() const { return m_pCurrent; } 211 212 /** retrieves the current element in the chain, or <NULL/> if the chain has been completely 213 traveled. 214 215 In opposite to the second <member>current</member>, this version allows typed access to 216 the respective SQLException. 217 */ 218 void current( SQLExceptionInfo& _out_rInfo ) const; 219 220 /** proceeds to the next element in the chain 221 222 @return the current element in the chain, as <b>before</em> the chain move. 223 */ 224 const ::com::sun::star::sdbc::SQLException* next(); 225 226 /** proceeds to the next element in the chain 227 228 In opposite to the second <member>current</member>, this version allows typed access to 229 the respective SQLException. 230 */ 231 void next( SQLExceptionInfo& _out_rInfo ); 232 }; 233 234 //================================================================================== 235 //= StandardExceptions 236 //================================================================================== 237 //---------------------------------------------------------------------------------- 238 /** returns a standard error string for a given SQLState 239 240 @param _eState 241 describes the state whose description is to retrieve. Must not be SQL_ERROR_UNSPECIFIED. 242 @raises RuntimeException 243 in case of an internal error 244 */ 245 OOO_DLLPUBLIC_DBTOOLS ::rtl::OUString getStandardSQLState( StandardSQLState _eState ); 246 247 //---------------------------------------------------------------------------------- 248 /** returns a standard ASCII string for a given SQLState 249 250 @param _eState 251 describes the state whose description is to retrieve. Must not be SQL_ERROR_UNSPECIFIED. 252 @return 253 a non-<NULL/> pointer to an ASCII character string denoting the requested SQLState 254 @raises RuntimeException 255 in case of an internal error 256 */ 257 OOO_DLLPUBLIC_DBTOOLS const sal_Char* getStandardSQLStateAscii( StandardSQLState _eState ); 258 259 //---------------------------------------------------------------------------------- 260 OOO_DLLPUBLIC_DBTOOLS void throwFunctionNotSupportedException( 261 const ::rtl::OUString& _rMsg, 262 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context, 263 const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any() 264 ) 265 throw ( ::com::sun::star::sdbc::SQLException ); 266 267 //---------------------------------------------------------------------------------- 268 /** throws an exception with SQL state IM001, saying that a certain function is not supported 269 */ 270 OOO_DLLPUBLIC_DBTOOLS void throwFunctionNotSupportedException( 271 const sal_Char* _pAsciiFunctionName, 272 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 273 const ::com::sun::star::uno::Any* _pNextException = NULL 274 ) 275 throw ( ::com::sun::star::sdbc::SQLException ); 276 277 //---------------------------------------------------------------------------------- 278 /** throws a function sequence (HY010) exception 279 */ 280 OOO_DLLPUBLIC_DBTOOLS void throwFunctionSequenceException( 281 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context, 282 const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any() 283 ) 284 throw ( ::com::sun::star::sdbc::SQLException ); 285 286 //---------------------------------------------------------------------------------- 287 /** throw a invalid index sqlexception 288 */ 289 OOO_DLLPUBLIC_DBTOOLS void throwInvalidIndexException( 290 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context, 291 const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any() 292 ) 293 throw ( ::com::sun::star::sdbc::SQLException ); 294 295 //---------------------------------------------------------------------------------- 296 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException 297 */ 298 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException( 299 const ::rtl::OUString& _rMsg, 300 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource 301 ) 302 throw (::com::sun::star::sdbc::SQLException); 303 304 //---------------------------------------------------------------------------------- 305 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException 306 */ 307 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException( 308 const ::rtl::OUString& _rMsg, 309 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource, 310 const ::com::sun::star::uno::Any& _rNextException 311 ) 312 throw (::com::sun::star::sdbc::SQLException); 313 314 //---------------------------------------------------------------------------------- 315 /** throw a SQLException with SQLState HYC00 (Optional feature not implemented) 316 @param _pAsciiFeatureName 317 an ASCII description of the feature which is not implemented. It's recommended that the feature 318 name is built from the name of the interface plus its method, for instance "XParameters::updateBinaryStream" 319 @param _rxContext 320 the context of the exception 321 @param _pNextException 322 the next exception to chain into the thrown exception, if any 323 */ 324 OOO_DLLPUBLIC_DBTOOLS void throwFeatureNotImplementedException( 325 const sal_Char* _pAsciiFeatureName, 326 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 327 const ::com::sun::star::uno::Any* _pNextException = NULL 328 ) 329 throw (::com::sun::star::sdbc::SQLException); 330 331 //---------------------------------------------------------------------------------- 332 /** throws an SQLException 333 */ 334 OOO_DLLPUBLIC_DBTOOLS void throwSQLException( 335 const sal_Char* _pAsciiMessage, 336 const sal_Char* _pAsciiState, 337 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 338 const sal_Int32 _nErrorCode = 0, 339 const ::com::sun::star::uno::Any* _pNextException = NULL 340 ) 341 throw (::com::sun::star::sdbc::SQLException); 342 343 //---------------------------------------------------------------------------------- 344 /** throws an SQLException 345 */ 346 OOO_DLLPUBLIC_DBTOOLS void throwSQLException( 347 const sal_Char* _pAsciiMessage, 348 StandardSQLState _eSQLState, 349 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 350 const sal_Int32 _nErrorCode = 0, 351 const ::com::sun::star::uno::Any* _pNextException = NULL 352 ) 353 throw (::com::sun::star::sdbc::SQLException); 354 355 //---------------------------------------------------------------------------------- 356 /** throws an SQLException 357 */ 358 OOO_DLLPUBLIC_DBTOOLS void throwSQLException( 359 const ::rtl::OUString& _rMessage, 360 StandardSQLState _eSQLState, 361 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 362 const sal_Int32 _nErrorCode = 0, 363 const ::com::sun::star::uno::Any* _pNextException = NULL 364 ) 365 throw (::com::sun::star::sdbc::SQLException); 366 367 //......................................................................... 368 } // namespace dbtools 369 //......................................................................... 370 371 #endif // _DBHELPER_DBEXCEPTION_HXX_ 372 373 374