TcpRecovery.h

Go to the documentation of this file.

// Copyright Onix Solutions Limited [OnixS]. All rights reserved.
//
// This software owned by Onix Solutions Limited [OnixS] and is
// protected by copyright law and international copyright treaties.
//
// Access to and use of the software is governed by the terms of the applicable
// OnixS Software Services Agreement (the Agreement) and Customer end user license
// agreements granting a non-assignable, non-transferable and non-exclusive license
// to use the software for it's own data processing purposes under the terms defined
// in the Agreement.
//
// Except as otherwise granted within the terms of the Agreement, copying or
// reproduction of any part of this source code or associated reference material
// to any other location for further reproduction or redistribution, and any
// amendments to this copyright notice, are expressly prohibited.
//
// Any reproduction or redistribution for sale or hiring of the Software not in
// accordance with the terms of the Agreement is a violation of copyright law.
//

#pragma once

#include <string>
#include <stdexcept>

#include <OnixS/CME/MDH/Watch.h>
#include <OnixS/CME/MDH/String.h>
#include <OnixS/CME/MDH/Integral.h>

ONIXS_CMEMDH_NAMESPACE_BEGIN

/// Throws error on zero TCP recovery request limit value.
inline void throwZeroTcpRecoveryRequestLimit()
{
    throw std::runtime_error("Maximal number of TCP Recovery requests per second must be greater than zero.");
}

/// TCP Recovery settings.
class ONIXS_CMEMDH_LTWT TcpRecoverySettings
{
public:
    /// <summary>
    /// The default value of acquisitionTimeout().
    /// </summary>
    enum { DefaultAcquisitionTimeout = 500 };

    /// <summary>
    /// The default value of maxRequests().
    /// </summary>
    enum { DefaultMaxRequests = 15 };

    TcpRecoverySettings()
        : username_()
        , password_()
        , acquisitionTimeout_(DefaultAcquisitionTimeout)
        , maxRequests_(DefaultMaxRequests)
        , watch_(&UtcWatch::service())
    {
    }

    TcpRecoverySettings(const std::string& username, const std::string& password)
        : username_(username)
        , password_(password)
        , acquisitionTimeout_(DefaultAcquisitionTimeout)
        , maxRequests_(DefaultMaxRequests)
        , watch_(&UtcWatch::service())
    {
    }

    ~TcpRecoverySettings() {}

    /// Username to identify a requester while
    /// logging on to a TCP Recovery service.
    const std::string& username() const
    {
        return username_;
    }

    /// Assigns username to identify a requester
    /// while logging on to a TCP Recovery service.
    TcpRecoverySettings& username(const std::string& username)
    {
        username_ = username;

        return *this;
    }

    /// Password to identify a requester while
    /// logging on to TCP Recovery service.
    const std::string& password() const
    {
        return password_;
    }

    /// Assigns password to identify a requester while logging on to TCP Recovery service.
    TcpRecoverySettings& password(const std::string& password)
    {
        password_ = password;

        return *this;
    }

    /// Returns the timeout (in milliseconds) on a TCP Recovery service acquisition.
    ///
    /// The recovery request will be rejected if the TCP recovery service cannot be acquired within this period.
    ///
    /// The default value is DefaultAcquisitionTimeout.
    UInt32 acquisitionTimeout() const
    {
        return acquisitionTimeout_;
    }

    /// Sets the timeout (in milliseconds) on a TCP Recovery service acquisition.
    ///
    /// The recovery request will be rejected if the TCP recovery service cannot be acquired within this period.
    TcpRecoverySettings& acquisitionTimeout(UInt32 acquisitionTimeout)
    {
        acquisitionTimeout_ = acquisitionTimeout;

        return *this;
    }

    /// Returns the maximum number of requests per second.
    ///
    /// When this limit is exceeded the recovery attempt is rejected.
    ///
    /// The default value is DefaultMaxRequests.
    UInt32 maxRequests() const
    {
        return maxRequests_;
    }

    /// Sets the maximum number of requests per second.
    ///
    /// When this limit is exceeded the recovery attempt is rejected.
    TcpRecoverySettings& maxRequests(UInt32 maxRequests)
    {
        if (0 < maxRequests)
        {
            maxRequests_ = maxRequests;
        }
        else
        {
            throwZeroTcpRecoveryRequestLimit();
        }

        return *this;
    }

    /// Watch service to be used by the service.
    ///
    /// Watch is used by the service while restricting
    /// number of incoming requests.
    ///
    /// @note By default, UTC watch service is used.
    WatchService& watch() const
    {
        return *watch_;
    }

    /// Watch service to be used by the service.
    ///
    /// If no instance associated, UTC watch is used.
    TcpRecoverySettings& watch(WatchService& watch)
    {
        watch_ = &watch;

        return *this;
    }

    private:
        std::string username_;
        std::string password_;

        UInt32 acquisitionTimeout_;

        UInt32 maxRequests_;

        WatchService* watch_;
};

/// Serializes TCP recovery settings.
ONIXS_CMEMDH_EXPORTED
void toStr(std::string&, const TcpRecoverySettings&);

/// Serializes TCP recovery settings.
inline std::string toStr(const TcpRecoverySettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

// A bit of declarations.
ONIXS_CMEMDH_EXPORTED_CLASS_DECL(Handler);

/// TCP Recovery Service.
class ONIXS_CMEMDH_EXPORTED TcpRecoveryService
{
public:
    /// Initializes instance according to given settings.
    TcpRecoveryService(const TcpRecoverySettings&);

    /// Finalizes instance and cleans everything up.
    virtual ~TcpRecoveryService();

    /// Basic information on the service.
    virtual void brief(std::string&);

    /// Gains access to the service.
    ///
    /// Returns login credentials through the
    /// parameters upon successful acquisition.
    virtual bool tryAcquire(const Handler&, StrRef&, StrRef&);

    /// Releases previously acquired lock on the service.
    virtual void release(const Handler&);

protected:
    /// Services as a marker for special construction.
    struct NoDetails
    {};

    /// Initializes without synchronization resource.
    explicit TcpRecoveryService(const NoDetails&);

private:
    class Details;

    // Shared details.
    Details* details_;

    // Copying is not assumed.

    TcpRecoveryService(const TcpRecoveryService&);

    TcpRecoveryService& operator=(const TcpRecoveryService&);
};

ONIXS_CMEMDH_NAMESPACE_END