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