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     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 /** throws an exception with SQL state IM001, saying that a certain function is not supported
 228 */
 229 OOO_DLLPUBLIC_DBTOOLS void throwFunctionNotSupportedException(
 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 //----------------------------------------------------------------------------------
 237 /** throws a function sequence (HY010) exception
 238 */
 239 OOO_DLLPUBLIC_DBTOOLS void throwFunctionSequenceException(
 240         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context,
 241         const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any()
 242     )
 243     throw ( ::com::sun::star::sdbc::SQLException );
 244
 245 //----------------------------------------------------------------------------------
 246 /** throw a invalid index sqlexception
 247 */
 248 OOO_DLLPUBLIC_DBTOOLS void throwInvalidIndexException(
 249         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _Context,
 250         const ::com::sun::star::uno::Any& _Next = ::com::sun::star::uno::Any()
 251     )
 252     throw ( ::com::sun::star::sdbc::SQLException );
 253
 254 //----------------------------------------------------------------------------------
 255 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException
 256 */
 257 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException(
 258         const OUString& _rMsg,
 259         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource
 260     )
 261     throw (::com::sun::star::sdbc::SQLException);
 262
 263 //----------------------------------------------------------------------------------
 264 /** throw a generic SQLException, i.e. one with an SQLState of HY000, an ErrorCode of 0 and no NextException
 265 */
 266 OOO_DLLPUBLIC_DBTOOLS void throwGenericSQLException(
 267         const OUString& _rMsg,
 268         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxSource,
 269         const ::com::sun::star::uno::Any& _rNextException
 270     )
 271     throw (::com::sun::star::sdbc::SQLException);
 272
 273 //----------------------------------------------------------------------------------
 274 /** throw a SQLException with SQLState HYC00 (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     @param _pNextException
 281         the next exception to chain into the thrown exception, if any
 282 */
 283 OOO_DLLPUBLIC_DBTOOLS void throwFeatureNotImplementedException(
 284         const OUString& _rFeatureName,
 285         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
 286         const ::com::sun::star::uno::Any* _pNextException = NULL
 287     )
 288     throw (::com::sun::star::sdbc::SQLException);
 289
 290 //----------------------------------------------------------------------------------
 291 /** throw a SQLException with SQLState 42S22 (Column Not Found)
 292     @param _rColumnNameName
 293         The column that couldn't be found.
 294     @param _rxContext
 295         the context of the exception
 296 */
 297 OOO_DLLPUBLIC_DBTOOLS void throwInvalidColumnException(
 298         const OUString& _rColumnName,
 299         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext
 300     )
 301     throw (::com::sun::star::sdbc::SQLException);
 302
 303 //----------------------------------------------------------------------------------
 304 /** throws an SQLException
 305 */
 306 OOO_DLLPUBLIC_DBTOOLS void throwSQLException(
 307         const OUString& _rMessage,
 308         const OUString& _rSQLState,
 309         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
 310         const sal_Int32 _nErrorCode = 0,
 311         const ::com::sun::star::uno::Any* _pNextException = NULL
 312     )
 313     throw (::com::sun::star::sdbc::SQLException);
 314
 315 //----------------------------------------------------------------------------------
 316 /** throws an SQLException
 317 */
 318 OOO_DLLPUBLIC_DBTOOLS void throwSQLException(
 319         const OUString& _rMessage,
 320         StandardSQLState _eSQLState,
 321         const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxContext,
 322         const sal_Int32 _nErrorCode = 0,
 323         const ::com::sun::star::uno::Any* _pNextException = NULL
 324     )
 325     throw (::com::sun::star::sdbc::SQLException);
 326
 327 //.........................................................................
 328 }   // namespace dbtools
 329 //.........................................................................
 330
 331 #endif // INCLUDED_CONNECTIVITY_DBEXCEPTION_HXX
 332
 333
 334 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */