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