include/connectivity/dbexception.hxx

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