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