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