include/connectivity/sqlerror.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_SQLERROR_HXX
  21 #define INCLUDED_CONNECTIVITY_SQLERROR_HXX
  22
  23 #include <com/sun/star/sdbc/SQLException.hpp>
  24 #include <com/sun/star/uno/XComponentContext.hpp>
  25 #include <connectivity/dbtoolsdllapi.hxx>
  26 #include <boost/optional.hpp>
  27 #include <memory>
  28
  29 namespace connectivity
  30 {
  31
  32
  33     //= ErrorCondition
  34
  35     /** the type of error codes to be used in SQLExceptions
  36
  37         @see css::sdbc::SQLException::ErrorCode
  38     */
  39     typedef ::sal_Int32 ErrorCode;
  40
  41     /** error condition values as defined in css::sdb::ErrorCondition
  42     */
  43     typedef ::sal_Int32 ErrorCondition;
  44
  45
  46     //= SQLError
  47
  48     class SQLError_Impl;
  49
  50     /** a class which provides helpers for working with SQLErrors
  51
  52         In particular, this class provides vendor-specific error codes (where
  53         the vendor is OpenOffice.org Base), which can be used in OOo's various
  54         database drivers, and checked in application-level code, to properly
  55         recognize highly specific error conditions.
  56
  57         @see css::sdb::ErrorCondition
  58     */
  59     class OOO_DLLPUBLIC_DBTOOLS SQLError
  60     {
  61     public:
  62
  63         // - optional
  64
  65         /** convenience wrapper around boost::optional, allowing implicit construction
  66         */
  67         class ParamValue : public ::boost::optional< OUString >
  68         {
  69             typedef ::boost::optional< OUString >  base_type;
  70
  71         public:
  72             ParamValue( ) : base_type( ) { }
  73             ParamValue( OUString const& val ) : base_type( val ) { }
  74             ParamValue( ParamValue const& rhs ) : base_type( (base_type const&)rhs ) { }
  75
  76             bool    is() const { return !base_type::operator!(); }
  77         };
  78
  79
  80     public:
  81         explicit        SQLError( const css::uno::Reference< css::uno::XComponentContext > & _rxContext );
  82                         ~SQLError();
  83
  84         /** returns the message associated with a given error condition, after (optionally) replacing
  85             a placeholder with a given string
  86
  87             Some error messages need to contain references to runtime-dependent data (say, the
  88             name of a concrete table in the database), which in the resource file's strings are
  89             represented by a placeholder, namely $1$, $2, and so on. This method allows to
  90             retrieve such an error message, and replace upo to 3 placeholders with their concrete
  91             values.
  92
  93             In a non-product build, assertions will fire if the number of placeholders in the
  94             message's resource string does not match the number of passed parameter values.
  95
  96             As specified in the css::sdb::ErrorCondition type,
  97             error messages thrown by core components of OpenOffice.org Base will contain
  98             a standardized prefix &quot;[OOoBase]&quot; in every message.
  99
 100             @see css::sdb::ErrorCondition
 101         */
 102         OUString getErrorMessage(
 103                             const ErrorCondition _eCondition
 104                         ) const;
 105
 106         /** returns the error code associated with a given error condition
 107
 108             @see getErrorMessage
 109             @see css::sdb::ErrorCondition
 110             @see css::sdbc::SQLException::ErrorCode
 111         */
 112         static ErrorCode
 113                         getErrorCode( const ErrorCondition _eCondition );
 114
 115         /** returns the prefix which is used for OpenOffice.org Base's error messages
 116
 117             As specified in the css::sdb::ErrorCondition type,
 118             error messages thrown by core components of OpenOffice.org Base will
 119             contain a standardized prefix in every message. <code>getBaseErrorMessagePrefix</code>
 120             returns this prefix, so clients of such error messages might decide to strip this
 121             prefix before presenting the message to the user, or use it to determine
 122             whether a concrete error has been raised by a OpenOffice.org core component.
 123         */
 124         static const OUString&
 125                         getMessagePrefix();
 126
 127
 128         /** throws an SQLException describing the given error condition
 129
 130             The thrown SQLException will contain the OOo-specific error code which derives
 131             from the given error condition, and the error message associated with that condition.
 132
 133             @param  _eCondition
 134                 the ErrorCondition which hit you
 135
 136             @param  _rxContext
 137                 the context in which the error occurred. This will be filled in as
 138                 <member scope="css::uno">Exception::Context</member> member.
 139
 140             @param _rParamValue1
 141                 a runtime-dependent value which should be filled into the error message
 142                 which is associated with <arg>_eCondition</arg>, replacing the first placeholder
 143                 in this message.
 144
 145             @param _rParamValue2
 146                 a runtime-dependent value which should be filled into the error message
 147                 which is associated with <arg>_eCondition</arg>, replacing the second placeholder
 148                 in this message.
 149
 150             @param _rParamValue3
 151                 a runtime-dependent value which should be filled into the error message
 152                 which is associated with <arg>_eCondition</arg>, replacing the third placeholder
 153                 in this message.
 154
 155             @see getErrorMessage
 156             @see getErrorCode
 157         */
 158         void            raiseException(
 159                             const ErrorCondition _eCondition,
 160                             const css::uno::Reference< css::uno::XInterface >& _rxContext,
 161                             const ParamValue& _rParamValue1 = ParamValue(),
 162                             const ParamValue& _rParamValue2 = ParamValue(),
 163                             const ParamValue& _rParamValue3 = ParamValue()
 164                         ) const;
 165
 166         /** throws an SQLException describing the given error condition
 167
 168             The thrown SQLException will contain the OOo-specific error code which derives
 169             from the given error condition, and the error message associated with that condition.
 170
 171             Note: You should prefer the version of raiseException which takes
 172             an additional Context parameter, since this allows clients of your
 173             exception to examine where the error occurred.
 174
 175             @param  _eCondition
 176                 the ErrorCondition which hit you
 177
 178             @see getErrorMessage
 179             @see getErrorCode
 180         */
 181         void            raiseException(
 182                             const ErrorCondition _eCondition
 183                         ) const;
 184
 185         /** raises a typed exception, that is, a UNO exception which is derived from
 186             css::sdbc::SQLException
 187
 188             @param  _eCondition
 189                 the ErrorCondition which hit you
 190
 191             @param  _rxContext
 192                 the context in which the error occurred. This will be filled in as
 193                 <member scope="css::uno">Exception::Context</member> member.
 194
 195             @param _rExceptionType
 196                 the type of the exception to throw. This type <em>must</em> specify
 197                 an exception class derived from css::sdbc::SQLException.
 198
 199             @throws ::std::bad_cast
 200                 if <arg>_rExceptionType</arg> does not specify an exception class derived from
 201                 css::sdbc::SQLException.
 202
 203             @see getErrorMessage
 204             @see getErrorCode
 205         */
 206         void            raiseTypedException(
 207                             const ErrorCondition _eCondition,
 208                             const css::uno::Reference< css::uno::XInterface >& _rxContext,
 209                             const css::uno::Type& _rExceptionType
 210                         ) const;
 211
 212         /** retrieves an <code>SQLException</code> object which contains information about
 213             the given error condition
 214
 215             @param  _eCondition
 216                 the ErrorCondition which hit you
 217
 218             @param  _rxContext
 219                 the context in which the error occurred. This will be filled in as
 220                 <member scope="css::uno">Exception::Context</member> member.
 221
 222             @param _rParamValue1
 223                 a runtime-dependent value which should be filled into the error message
 224                 which is associated with <arg>_eCondition</arg>, replacing the first placeholder
 225                 in this message.
 226
 227             @param _rParamValue2
 228                 a runtime-dependent value which should be filled into the error message
 229                 which is associated with <arg>_eCondition</arg>, replacing the second placeholder
 230                 in this message.
 231
 232             @param _rParamValue3
 233                 a runtime-dependent value which should be filled into the error message
 234                 which is associated with <arg>_eCondition</arg>, replacing the third placeholder
 235                 in this message.
 236
 237             @see getErrorMessage
 238             @see getErrorCode
 239         */
 240         css::sdbc::SQLException
 241                         getSQLException(
 242                             const ErrorCondition _eCondition,
 243                             const css::uno::Reference< css::uno::XInterface >& _rxContext,
 244                             const ParamValue& _rParamValue1 = ParamValue(),
 245                             const ParamValue& _rParamValue2 = ParamValue(),
 246                             const ParamValue& _rParamValue3 = ParamValue()
 247                         ) const;
 248
 249     private:
 250         std::shared_ptr< SQLError_Impl > m_pImpl;
 251     };
 252
 253
 254 } // namespace connectivity
 255
 256
 257 #endif // INCLUDED_CONNECTIVITY_SQLERROR_HXX
 258
 259 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */