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/ConflatedUDP/Watch.h>
#include <OnixS/CME/ConflatedUDP/String.h>
#include <OnixS/CME/ConflatedUDP/Integral.h>


ONIXS_CONFLATEDUDP_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 service configuration settings.
ONIXS_CONFLATEDUDP_LTWT_CLASS
TcpRecoverySettings
{
    std::string username_;
    std::string password_;

    UInt32 acquisitionTimeout_;

    UInt32 maxRequests_;

    WatchService* watch_;

public:
    /// Initializes parameters with default values.
    TcpRecoverySettings()
        : username_()
        , password_()
        , acquisitionTimeout_(500)
        , maxRequests_(15)
        , watch_(&UtcWatch::service())
    {
    }

    /// Cleans everything up.
    ~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.
    void 
    username(
        const std::string& username)
    {
        username_ = username;
    }

    /// 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.
    void 
    password(
        const std::string& password)
    {
        password_ = password;
    }

    /// Timeout on a TCP recovery service acquisition.
    /// 
    /// TCP recovery service may process only 
    /// single request at a time. If TCP recovery 
    /// service can't be acquired within time defined 
    /// by given parameter, recovery request will be 
    /// rejected. 
    ///
    /// Timeout is measured in milliseconds. 
    ///
    /// @note Default value is '500'. 
    UInt32 
    acquisitionTimeout() const
    {
        return acquisitionTimeout_;
    }

    /// Defines the wait time limit while 
    /// acquiring a TCP recovery service.
    /// 
    /// If TCP recovery service is used and the 
    /// other Handler instance gained access to 
    /// the service to recover missing data, the 
    /// Handler instance will wait for the given 
    /// time to acquire the service and will cancel 
    /// the TCP recovery request if service wasn't 
    /// acquired for the given time period.
    ///
    /// Timeout is measured in milliseconds. 
    void 
    acquisitionTimeout(
        UInt32 acquisitionTimeout)
    {
        acquisitionTimeout_ = 
            acquisitionTimeout;
    }

    /// Maximal number of requests per second.
    ///
    /// By default, the service is limited 
    /// to serve 15 requests per second. 
    UInt32 maxRequests() const
    {
        return maxRequests_;
    }

    /// Limits number of requests per second.
    /// 
    /// If the established limit is exceeded a 
    /// recovery attempt is rejected by service.
    void 
    maxRequests(
        UInt32 maxRequests)
    {
        if (0 < maxRequests)
        {
            maxRequests_ = maxRequests;
        }
        else
        {
            throwZeroTcpRecoveryRequestLimit();
        }
    }

    /// 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. 
    void 
    watch(
        WatchService& watch)
    {
        watch_ = &watch;
    }
};

/// Serializes TCP recovery settings. 
ONIXS_CONFLATEDUDP_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_CONFLATEDUDP_EXPORTED_CLASS_DECL
(
    Handler
);

/// TCP Recovery Service.
ONIXS_CONFLATEDUDP_EXPORTED_CLASS
TcpRecoveryService
{
    class Details;

    // Shared details. 
    Details* details_;

    // Copying is not assumed. 

    TcpRecoveryService(
        const TcpRecoveryService&);

    TcpRecoveryService& 
    operator =(
        const TcpRecoveryService&);

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

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

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&);
};

ONIXS_CONFLATEDUDP_NAMESPACE_END