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