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 266 //---------------------------------------------------------------------------------- 267 /** throws an exception with SQL state IM001, saying that a certain function is not supported 268 */ 269 OOO_DLLPUBLIC_DBTOOLS void throwFunctionNotSupportedException( 270 const sal_Char* _pAsciiFunctionName, 271 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 272 const ::com::sun::star::uno::Any* _pNextException = NULL 273 ); 274 275 //---------------------------------------------------------------------------------- 276 /** throws a function sequence (HY010) exception 277 */ 278 OOO_DLLPUBLIC_DBTOOLS void throwFunctionSequenceException( 279 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context, 280 const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any() 281 ); 282 283 //---------------------------------------------------------------------------------- 284 /** throw a invalid index sqlexception 285 */ 286 OOO_DLLPUBLIC_DBTOOLS void throwInvalidIndexException( 287 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context, 288 const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any() 289 ); 290 291 //---------------------------------------------------------------------------------- 292 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException 293 */ 294 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException( 295 const ::rtl::OUString& _rMsg, 296 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource 297 ); 298 299 //---------------------------------------------------------------------------------- 300 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException 301 */ 302 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException( 303 const ::rtl::OUString& _rMsg, 304 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource, 305 const ::com::sun::star::uno::Any& _rNextException 306 ); 307 308 //---------------------------------------------------------------------------------- 309 /** throw a SQLException with SQLState HYC00 (Optional feature not implemented) 310 @param _pAsciiFeatureName 311 an ASCII description of the feature which is not implemented. It's recommended that the feature 312 name is built from the name of the interface plus its method, for instance "XParameters::updateBinaryStream" 313 @param _rxContext 314 the context of the exception 315 @param _pNextException 316 the next exception to chain into the thrown exception, if any 317 */ 318 OOO_DLLPUBLIC_DBTOOLS void throwFeatureNotImplementedException( 319 const sal_Char* _pAsciiFeatureName, 320 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 321 const ::com::sun::star::uno::Any* _pNextException = NULL 322 ); 323 324 //---------------------------------------------------------------------------------- 325 /** throws an SQLException 326 */ 327 OOO_DLLPUBLIC_DBTOOLS void throwSQLException( 328 const sal_Char* _pAsciiMessage, 329 const sal_Char* _pAsciiState, 330 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 331 const sal_Int32 _nErrorCode = 0, 332 const ::com::sun::star::uno::Any* _pNextException = NULL 333 ); 334 335 //---------------------------------------------------------------------------------- 336 /** throws an SQLException 337 */ 338 OOO_DLLPUBLIC_DBTOOLS void throwSQLException( 339 const sal_Char* _pAsciiMessage, 340 StandardSQLState _eSQLState, 341 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 342 const sal_Int32 _nErrorCode = 0, 343 const ::com::sun::star::uno::Any* _pNextException = NULL 344 ); 345 346 //---------------------------------------------------------------------------------- 347 /** throws an SQLException 348 */ 349 OOO_DLLPUBLIC_DBTOOLS void throwSQLException( 350 const ::rtl::OUString& _rMessage, 351 StandardSQLState _eSQLState, 352 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext, 353 const sal_Int32 _nErrorCode = 0, 354 const ::com::sun::star::uno::Any* _pNextException = NULL 355 ); 356 357 //......................................................................... 358 } // namespace dbtools 359 //......................................................................... 360 361 #endif // _DBHELPER_DBEXCEPTION_HXX_ 362