Quelle  sqlerror.hxx

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

#ifndef INCLUDED_CONNECTIVITY_SQLERROR_HXX
#define INCLUDED_CONNECTIVITY_SQLERROR_HXX

#include <config_options.h>
#include <com/sun/star/sdbc/SQLException.hpp>
#include <connectivity/dbtoolsdllapi.hxx>
#include <optional>
#include <memory>

namespace connectivity
{


    //= ErrorCondition

    /** the type of error codes to be used in SQLExceptions

        @see css::sdbc::SQLException::ErrorCode
    */
    typedef ::sal_Int32 ErrorCode;

    /** error condition values as defined in css::sdb::ErrorCondition
    */
    typedef ::sal_Int32 ErrorCondition;


    //= SQLError

    class SQLError_Impl;

    /** a class which provides helpers for working with SQLErrors

        In particular, this class provides vendor-specific error codes (where
        the vendor is OpenOffice.org Base), which can be used in OOo's various
        database drivers, and checked in application-level code, to properly
        recognize highly specific error conditions.

        @see css::sdb::ErrorCondition
    */
    class UNLESS_MERGELIBS_MORE(OOO_DLLPUBLIC_DBTOOLS) SQLError
    {
    public:
                        SQLError();
                        ~SQLError();

        /** returns the message associated with a given error condition, after (optionally) replacing
            a placeholder with a given string

            Some error messages need to contain references to runtime-dependent data (say, the
            name of a concrete table in the database), which in the resource file's strings are
            represented by a placeholder, namely $1$, $2, and so on. This method allows to
            retrieve such an error message, and replace up to 3 placeholders with their concrete
            values.

            In a non-product build, assertions will fire if the number of placeholders in the
            message's resource string does not match the number of passed parameter values.

            As specified in the css::sdb::ErrorCondition type,
            error messages thrown by core components of OpenOffice.org Base will contain
            a standardized prefix &quot;[OOoBase]&quot; in every message.

            @see css::sdb::ErrorCondition
        */
        OUString getErrorMessage(
                            const ErrorCondition _eCondition
                        ) const;

        /** returns the error code associated with a given error condition

            @see getErrorMessage
            @see css::sdb::ErrorCondition
            @see css::sdbc::SQLException::ErrorCode
        */
        static ErrorCode
                        getErrorCode( const ErrorCondition _eCondition );

        /** returns the prefix which is used for OpenOffice.org Base's error messages

            As specified in the css::sdb::ErrorCondition type,
            error messages thrown by core components of OpenOffice.org Base will
            contain a standardized prefix in every message. <code>getBaseErrorMessagePrefix</code>
            returns this prefix, so clients of such error messages might decide to strip this
            prefix before presenting the message to the user, or use it to determine
            whether a concrete error has been raised by a OpenOffice.org core component.
        */
        static const OUString&
                        getMessagePrefix();


        /** throws an SQLException describing the given error condition

            The thrown SQLException will contain the OOo-specific error code which derives
            from the given error condition, and the error message associated with that condition.

            @param  _eCondition
                the ErrorCondition which hit you

            @param  _rxContext
                the context in which the error occurred. This will be filled in as
                <member scope="css::uno">Exception::Context</member> member.

            @param _rParamValue1
                a runtime-dependent value which should be filled into the error message
                which is associated with <arg>_eCondition</arg>, replacing the first placeholder
                in this message.

            @param _rParamValue2
                a runtime-dependent value which should be filled into the error message
                which is associated with <arg>_eCondition</arg>, replacing the second placeholder
                in this message.

            @param _rParamValue3
                a runtime-dependent value which should be filled into the error message
                which is associated with <arg>_eCondition</arg>, replacing the third placeholder
                in this message.

            @see getErrorMessage
            @see getErrorCode
        */
        void            raiseException(
                            const ErrorCondition _eCondition,
                            const css::uno::Reference< css::uno::XInterface >& _rxContext,
                            const std::optional<OUString>& _rParamValue1 = std::nullopt,
                            const std::optional<OUString>& _rParamValue2 = std::nullopt,
                            const std::optional<OUString>& _rParamValue3 = std::nullopt
                        ) const;

        /** throws an SQLException describing the given error condition

            The thrown SQLException will contain the OOo-specific error code which derives
            from the given error condition, and the error message associated with that condition.

            Note: You should prefer the version of raiseException which takes
            an additional Context parameter, since this allows clients of your
            exception to examine where the error occurred.

            @param  _eCondition
                the ErrorCondition which hit you

            @see getErrorMessage
            @see getErrorCode
        */
        void            raiseException(
                            const ErrorCondition _eCondition
                        ) const;

        /** raises a typed exception, that is, a UNO exception which is derived from
            css::sdbc::SQLException

            @param  _eCondition
                the ErrorCondition which hit you

            @param  _rxContext
                the context in which the error occurred. This will be filled in as
                <member scope="css::uno">Exception::Context</member> member.

            @param _rExceptionType
                the type of the exception to throw. This type <em>must</em> specify
                an exception class derived from css::sdbc::SQLException.

            @throws ::std::bad_cast
                if <arg>_rExceptionType</arg> does not specify an exception class derived from
                css::sdbc::SQLException.

            @see getErrorMessage
            @see getErrorCode
        */
        void            raiseTypedException(
                            const ErrorCondition _eCondition,
                            const css::uno::Reference< css::uno::XInterface >& _rxContext,
                            const css::uno::Type& _rExceptionType
                        ) const;

        /** retrieves an <code>SQLException</code> object which contains information about
            the given error condition

            @param  _eCondition
                the ErrorCondition which hit you

            @param  _rxContext
                the context in which the error occurred. This will be filled in as
                <member scope="css::uno">Exception::Context</member> member.

            @param _rParamValue1
                a runtime-dependent value which should be filled into the error message
                which is associated with <arg>_eCondition</arg>, replacing the first placeholder
                in this message.

            @param _rParamValue2
                a runtime-dependent value which should be filled into the error message
                which is associated with <arg>_eCondition</arg>, replacing the second placeholder
                in this message.

            @param _rParamValue3
                a runtime-dependent value which should be filled into the error message
                which is associated with <arg>_eCondition</arg>, replacing the third placeholder
                in this message.

            @see getErrorMessage
            @see getErrorCode
        */
        css::sdbc::SQLException
                        getSQLException(
                            const ErrorCondition _eCondition,
                            const css::uno::Reference< css::uno::XInterface >& _rxContext,
                            const std::optional<OUString>& _rParamValue1 = std::nullopt,
                            const std::optional<OUString>& _rParamValue2 = std::nullopt,
                            const std::optional<OUString>& _rParamValue3 = std::nullopt
                        ) const;

    private:
        std::shared_ptr< SQLError_Impl > m_pImpl;
    };


} // namespace connectivity


#endif // INCLUDED_CONNECTIVITY_SQLERROR_HXX

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */