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