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