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