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 <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  _rSQLState
  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 OUString& _rSQLState = OUString(), 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  _rSQLState
 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 OUString& _rSQLState = OUString(), 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     bool        isKindOf(TYPE _eType) const;
 131         // not just a simple comparisation ! e.g. getType() == SQL_CONTEXT implies isKindOf(SQL_EXCEPTION) == sal_True !
 132     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     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 /** throws an exception with SQL state IM001, saying that a certain function is not supported
 228 */
 229 OOO_DLLPUBLIC_DBTOOLS void throwFunctionNotSupportedSQLException(
 230         const OUString& _rFunctionName,
 231         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
 232         const ::com::sun::star::uno::Any& _rNextException = ::com::sun::star::uno::Any()
 233     )
 234     throw ( ::com::sun::star::sdbc::SQLException );
 235
 236 OOO_DLLPUBLIC_DBTOOLS void throwFunctionNotSupportedRuntimeException(
 237         const OUString& _rFunctionName,
 238         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext
 239     )
 240     throw (css::uno::RuntimeException );
 241
 242 /** throws a function sequence (HY010) exception
 243 */
 244 OOO_DLLPUBLIC_DBTOOLS void throwFunctionSequenceException(
 245         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context,
 246         const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any()
 247     )
 248     throw ( ::com::sun::star::sdbc::SQLException );
 249
 250
 251 /** throw a invalid index sqlexception
 252 */
 253 OOO_DLLPUBLIC_DBTOOLS void throwInvalidIndexException(
 254         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context,
 255         const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any()
 256     )
 257     throw ( ::com::sun::star::sdbc::SQLException );
 258
 259
 260 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException
 261 */
 262 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException(
 263         const OUString& _rMsg,
 264         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource
 265     )
 266     throw (::com::sun::star::sdbc::SQLException);
 267
 268
 269 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException
 270 */
 271 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException(
 272         const OUString& _rMsg,
 273         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource,
 274         const ::com::sun::star::uno::Any& _rNextException
 275     )
 276     throw (::com::sun::star::sdbc::SQLException);
 277
 278
 279 /** throw a SQLException with SQLState HYC00 (Optional feature not implemented)
 280     @param _rFeatureName
 281         a description of the feature which is not implemented. It's recommended that the feature
 282         name is built from the name of the interface plus its method, for instance "XParameters::updateBinaryStream"
 283     @param _rxContext
 284         the context of the exception
 285     @param _pNextException
 286         the next exception to chain into the thrown exception, if any
 287 */
 288 OOO_DLLPUBLIC_DBTOOLS void throwFeatureNotImplementedSQLException(
 289         const OUString& _rFeatureName,
 290         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
 291         const ::com::sun::star::uno::Any* _pNextException = NULL
 292     )
 293     throw (css::sdbc::SQLException);
 294
 295 /** throw a RuntimeException (Optional feature not implemented)
 296     @param _rFeatureName
 297         a description of the feature which is not implemented. It's recommended that the feature
 298         name is built from the name of the interface plus its method, for instance "XParameters::updateBinaryStream"
 299     @param _rxContext
 300         the context of the exception
 301     @param _pNextException
 302         the next exception to chain into the thrown exception, if any
 303 */
 304 OOO_DLLPUBLIC_DBTOOLS void throwFeatureNotImplementedRuntimeException(
 305         const OUString& _rFeatureName,
 306         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext
 307     )
 308     throw (css::uno::RuntimeException);
 309
 310 /** throw a SQLException with SQLState 42S22 (Column Not Found)
 311     @param _rColumnNameName
 312         The column that couldn't be found.
 313     @param _rxContext
 314         the context of the exception
 315 */
 316 OOO_DLLPUBLIC_DBTOOLS void throwInvalidColumnException(
 317         const OUString& _rColumnName,
 318         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext
 319     )
 320     throw (::com::sun::star::sdbc::SQLException);
 321
 322
 323 /** throws an SQLException
 324 */
 325 OOO_DLLPUBLIC_DBTOOLS void throwSQLException(
 326         const OUString& _rMessage,
 327         const OUString& _rSQLState,
 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 // INCLUDED_CONNECTIVITY_DBEXCEPTION_HXX
 351
 352
 353 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */