LCOV - code coverage report
Current view: top level - include/connectivity - sqlerror.hxx (source / functions) Hit Total Coverage
Test: commit e02a6cb2c3e2b23b203b422e4e0680877f232636 Lines: 0 5 0.0 %
Date: 2014-04-14 Functions: 0 5 0.0 %
Legend: Lines: hit not hit

          Line data    Source code
       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             : 
      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 com::sun::star::sdb::ErrorCondition
      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           0 :         class ParamValue : public ::boost::optional< OUString >
      71             :         {
      72             :             typedef ::boost::optional< OUString >  base_type;
      73             : 
      74             :         public:
      75           0 :             ParamValue( ) : base_type( ) { }
      76           0 :             ParamValue( OUString const& val ) : base_type( val ) { }
      77           0 :             ParamValue( ParamValue const& rhs ) : base_type( (base_type const&)rhs ) { }
      78             : 
      79           0 :             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 com::sun::star::sdb::ErrorCondition 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 com::sun::star::sdb::ErrorCondition 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 raiseException which takes
     194             :             an additional Context 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             :             com::sun::star::sdbc::SQLException
     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 com::sun::star::sdbc::SQLException.
     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             :                 com::sun::star::sdbc::SQLException.
     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 // INCLUDED_CONNECTIVITY_SQLERROR_HXX
     316             : 
     317             : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Generated by: LCOV version 1.10