FeedSettings.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 <OnixS/CME/MDH/Domain.h>
#include <OnixS/CME/MDH/PacketTraits.h>
#include <OnixS/CME/MDH/SettingGroup.h>

ONIXS_CMEMDH_NAMESPACE_BEGIN

// A bit of forward declarations.

ONIXS_CMEMDH_EXPORTED_CLASS_DECL
(
    NetFeedEngine
);

/// List of hosts as a setting. 
typedef 
ListSetting<std::string>
HostListSetting;

/// List of network interfaces as a setting. 
typedef 
HostListSetting
NifListSetting;

/// Deserializes host list setting from a string. 
ONIXS_CMEMDH_EXPORTED
void 
fromStr(
    HostListSetting&, 
    const std::string&);

/// The collection of parameters defining feed connection.
ONIXS_CMEMDH_LTWT_CLASS
FeedConnectionSettings
{
    const SettingGroup& group_;

    UInt32 port_;
    std::string ip_;

    HostListSetting hosts_;
    NifListSetting nifs_;

    std::string id_;

    // Non-guarded assignment. 
    void
    assignNoControl(
        const 
        FeedConnectionSettings& other)
    {
        port_ = other.port_;
        ip_ = other.ip_;

        hosts_.assignNoControl(other.hosts_);
        nifs_.assignNoControl(other.nifs_);
        
        id_ = other.id_;
    }

public:
    // Makes assignment more flexible. 
    template
    <
        class
    >
    friend 
    ONIXS_CMEMDH_LTWT_CLASS_DECL
    (
        FeedSettingsBase
    );

    /// Initializes as a blank instance. 
    FeedConnectionSettings(
        const SettingGroup* group = NULL)
        : group_(
            group
            ? *group
            : SettingGroup::null())
        , port_(0)
        , hosts_(group)
        , nifs_(group)
    {
    }

    /// Initializes the given instance 
    /// as a copy of the other one. 
    FeedConnectionSettings(
        const FeedConnectionSettings& other)
        : group_(SettingGroup::null())
        , port_(other.port_)
        , ip_(other.ip_)
        , hosts_(other.hosts_)
        , nifs_(other.nifs_)
        , id_(other.id_)
    {
    }

    /// Finalizes the instance.
    ~FeedConnectionSettings()
    {
    }

    /// Port component of the given connection settings.
    UInt32 port() const
    {
        return port_;
    }

    /// Updates port number for the given connection settings.
    FeedConnectionSettings& 
    port(
        UInt32 port)
    {
        group_.
            controlAssignment
            (
                "Port",
                port_, 
                port
            );

        return *this;
    }

    /// Indicates address component of the given connection settings.
    /// 
    /// For the multicast type of connection the given parameter indicates 
    /// a multicast group to join to. For the streamed/TCP connections the 
    /// given parameter indicates the remote host to connect to. 
    const 
    std::string& 
    ip() const
    {
        return ip_;
    }

    /// Updates address component of the given connection settings.
    /// 
    /// For the multicast type of connection the given parameter indicates 
    /// a multicast group to join to. For the streamed/TCP connections the 
    /// given parameter indicates the remote host to connect to. 
    FeedConnectionSettings& 
    ip(
        const std::string& address)
    {
        group_.
            controlAssignment
            (
                "IP Address",
                ip_, 
                address
            );

        return *this;
    }

    /// Indicates host list of the given connection settings.
    /// 
    /// This component is the optional one and may be used to supply 
    /// additional information on the connection. For example, if the 
    /// connection is the multicast one, the given parameter represents 
    /// a list of remote hosts from which the multicast data is actually 
    /// transmitted. Also, CME doesn't use IP parameter while defining 
    /// connections for the TCP Recovery feeds in the connectivity 
    /// configuration file (config.xml). Instead, this one is used. 
    const 
    HostListSetting& 
    hosts() const
    {
        return hosts_;
    }

    /// Updates list of hosts for the given connection settings.
    /// 
    /// This component is the optional one and may be used to supply 
    /// additional information on the connection. For example, if the 
    /// connection is the multicast one, the given parameter represents 
    /// a list of remote hosts from which the multicast data is actually 
    /// transmitted. Also, CME doesn't use IP parameter while defining 
    /// connections for the TCP Recovery feeds in the connectivity 
    /// configuration file (config.xml). Instead, this one is used. 
    HostListSetting&
    hosts()
    {
        return hosts_;
    }

    /// Updates list of hosts for the given connection settings from a 
    /// string representing comma or semi-colon separated list of hosts.
    /// 
    /// This component is the optional one and may be used to supply 
    /// additional information on the connection. For example, if the 
    /// connection is the multicast one, the given parameter represents 
    /// a list of remote hosts from which the multicast data is actually 
    /// transmitted. Also, CME doesn't use IP parameter while defining 
    /// connections for the TCP Recovery feeds in the connectivity 
    /// configuration file (config.xml). Instead, this one is used. 
    FeedConnectionSettings& 
    hosts(
        const std::string& hosts)
    {
        fromStr(hosts_, hosts);

        return *this; 
    }

    /// List of network interfaces for the given connection settings. 
    ///
    /// If the settings refers to a multicast group, the given parameter 
    /// indicates a list of network interfaces on which the multicast
    /// data must be listen to. 
    const 
    NifListSetting& 
    networkInterfaces() const
    {
        return nifs_;
    }

    /// List of network interfaces for the given connection settings. 
    ///
    /// If the settings refers to a multicast group, the given parameter 
    /// indicates a list of network interfaces on which the multicast
    /// data must be listen to. 
    NifListSetting& 
    networkInterfaces()
    {
        return nifs_;
    }

    /// Specifies one or more network interfaces on which to join the 
    /// multicast group if the settings define multicast connection. 
    /// Use semi-colon delimited list to specify multiple interfaces.
    /// 
    /// @note On Linux the network interface is specified by its name, 
    /// on Windows - by IP address.
    FeedConnectionSettings& 
    networkInterfaces(
        const std::string& interfaces)
    {
        fromStr(nifs_, interfaces);

        return *this; 
    }

    /// The unique connection/feed identifier.
    const 
    std::string& 
    id() const
    {
        return id_;
    }

    /// Updates the connection/feed identifier. 
    FeedConnectionSettings& 
    id(
        const 
        std::string& id)
    {
        group_.
            controlAssignment
            (
                "Identifier",
                id_,
                id
            );

        return *this; 
    }

    /// Re-initializes the instance as a copy of the other one. 
    FeedConnectionSettings&
    operator =(
        const 
        FeedConnectionSettings& other)
    {
        group_.
            controlChange
            (
                "Feed Connection Settings",
                &FeedConnectionSettings::assignNoControl,
                *this,
                other
            );

        return *this;
    }
};

/// Serializes feed connection parameters into a string.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    const FeedConnectionSettings&);

/// Serializes feed connection parameters into a string.
inline
std::string
toStr(
    const 
    FeedConnectionSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

/// Collection of parameters which are common for all types of feeds.
template
<
    typename Layout
>
class 
FeedSettingsBase
{
    const SettingGroup& group_;

    Layout layout_;
    UInt32 heartbeatInterval_;

    FeedConnectionSettings A_;
    FeedConnectionSettings B_;

    FeedSettingsBase&
    operator =(
        const 
        FeedSettingsBase& other);

protected:
    // Makes assignment more flexible. 
    friend
    ONIXS_CMEMDH_LTWT_CLASS_DECL
    (
        FeedSettings
    );

    /// Initializes the instance with the 
    /// given values and optional grouping.
    FeedSettingsBase(
        const SettingGroup* group, 
        Layout layout, UInt32 heartbeat)
        : group_(
            group
            ? *group
            : SettingGroup::null())
        , layout_(layout)
        , heartbeatInterval_(heartbeat)
        , A_(group)
        , B_(group)
    {
    }

    /// Initializes the instance 
    /// as a copy of the other one. 
    /// 
    /// Attributes controlling value 
    /// assignment aren't cloned and 
    /// thus only settings are copied. 
    FeedSettingsBase(
        const 
        FeedSettingsBase& other)
        : group_(SettingGroup::null())
        , layout_(other.layout_)
        , heartbeatInterval_(
            other.heartbeatInterval_)
        , A_(other.A_)
        , B_(other.B_)
    {
    }

    // Finalizes the instance. 
    ~FeedSettingsBase()
    {
    }

    /// Instance of the group which 
    /// the given settings belong to. 
    const 
    SettingGroup& 
    group() const
    {
        return group_;
    }

    /// Re-initializes the instance as a 
    /// copy of the other one without involving 
    /// assignment control services. 
    void
    assignNoControl(
        const FeedSettingsBase& other)
    {
        layout_ = 
            other.layout_;

        heartbeatInterval_ = 
            other.heartbeatInterval_;

        A_.assignNoControl(other.A_);
        B_.assignNoControl(other.B_);
    }

public:
    /// Defines feed layout for a feed group.
    Layout layout() const
    {
        return layout_;
    }

    /// Defines feed layout for recovery feed group.
    FeedSettingsBase& 
    layout(
        Layout value)
    {
        group_.
            controlAssignment
            (
                "Layout",
                layout_, 
                value
            );

        return *this;
    }

    /// Specifies maximal time interval between two
    /// network packets. If no data is received during
    /// specified time frame, corresponding event is raised 
    /// and further behavior is defined by feed layout. 
    ///
    /// Interval is measured in seconds. 
    UInt32 
    heartbeatInterval() const
    {
        return heartbeatInterval_;
    }

    /// Specifies maximal time interval between two packets. 
    FeedSettingsBase& 
    heartbeatInterval(
        UInt32 interval)
    {
        group_.
            controlAssignment
            (
                "Heartbeat Interval",
                heartbeatInterval_, 
                interval
            );

        return *this; 
    }

    /// Connection attributes for the primary (A) feed. 
    FeedConnectionSettings& 
    A()
    {
        return A_;
    }

    /// Connection attributes for the primary (A) feed. 
    const 
    FeedConnectionSettings& 
    A() const 
    {
        return A_;
    }

    /// Connection attributes for the secondary (B) feed. 
    FeedConnectionSettings& 
    B()
    {
        return B_;
    }

    /// Connection attributes for the secondary (B) feed. 
    const 
    FeedConnectionSettings& 
    B() const 
    {
        return B_;
    }

#if !defined (ONIXS_CMEMDH_NO_DEPRECATED)

    /// Specifies one or more network interfaces to use for 
    /// primary (A) feeds while joining the multicast group.
    /// Use semi-colon to delimit multiple interfaces.
    /// 
    /// @note On Linux the network interface is specified 
    /// by its name, on Windows - by IP address.
    /// 
    /// @warning The given member is deprecated. 
    /// Use feed connection settings instead. 
    FeedSettingsBase& 
    feedANetworkInterfaces(
        const std::string& interfaces)
    {
        A_.networkInterfaces(interfaces);

        return *this; 
    }

    /// Specifies one or more network interfaces to use for 
    /// secondary (B) feeds while joining the multicast group.
    /// Use semi-colon to delimit multiple interfaces.
    /// 
    /// @note On Linux the network interface is specified 
    /// by its name, on Windows - by IP address.
    /// 
    /// @warning The given member is deprecated. 
    /// Use feed connection settings instead. 
    FeedSettingsBase& 
    feedBNetworkInterfaces(
        const std::string& interfaces)
    {
        B_.networkInterfaces(interfaces);

        return *this; 
    }

#endif // !ONIXS_CMEMDH_NO_DEPRECATED
};

/// Defines feed layout alternates available for 
/// recovery feeds like instrument and snapshot. 
ONIXS_CMEMDH_LTWT_STRUCT RecoveryFeedLayout
{
    /// Integral type used as basement for constants. 
    typedef UInt32 Base;

    enum Enum
    {
        /// Indicates only feed A is used as source for market data. 
        FeedAOnly,

        /// Indicates only feed B is used as source for market data. 
        FeedBOnly,

        /// Feed A is used as primary source of market data. If Handler
        /// detects absence of market data on feed A, it switches to 
        /// feed B to continue market data processing. Feed B is used 
        /// by Handler until market data absence is detected on it. In 
        /// that case Handler will switch back to feed A. In other words,
        /// this layout instructs Handler to cycle between feeds if data
        /// absence is detected starting from feed A.
        FeedAWithFailoverToFeedB,

        /// Feed B is used as primary source of market data. If Handler
        /// detects absence of market data on feed B, it switches to 
        /// feed A to continue market data processing. Feed A is used 
        /// by Handler until market data absence is detected on it. In 
        /// that case Handler will switch back to feed B. In other words,
        /// this layout instructs Handler to cycle between feeds if data
        /// absence is detected starting from feed B.
        FeedBWithFailoverToFeedA
    };
};

/// Appends string presentation of feed layout.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    RecoveryFeedLayout::Enum);

/// Returns string presentation of feed layout.
inline 
std::string
toStr(
    RecoveryFeedLayout::Enum layout)
{
    std::string str;
    
    toStr(str, layout);
    
    return str;
}

/// Collection of parameters affecting recovery feeds behavior. 
ONIXS_CMEMDH_LTWT_CLASS
MulticastRecoveryFeedSettings
: public FeedSettingsBase
  <
    RecoveryFeedLayout::Enum
  >
{
    friend
    ONIXS_CMEMDH_LTWT_CLASS_DECL
    (
        FeedSettings
    );

    typedef 
    FeedSettingsBase
    <
        RecoveryFeedLayout::Enum
    >
    Base;

    void
    assignNoControl(
        const 
        MulticastRecoveryFeedSettings& other)
    {
        Base::assignNoControl(other);
    }

public:
    /// Initializes instance with default values. 
    /// 
    /// By default, feed A is used as the primary source 
    /// of market recovery data with fail-over to the feed B. 
    /// Heartbeats are expected within 30 seconds periodicity.
    MulticastRecoveryFeedSettings(
        const SettingGroup* group = NULL)
    : Base(
        group, 
        RecoveryFeedLayout::
        FeedAWithFailoverToFeedB,
        30)
    {
    }

    /// Initializes the instance as a copy of the other one. 
    MulticastRecoveryFeedSettings(
        const MulticastRecoveryFeedSettings& other)
        : Base(static_cast<const Base&>(other))
    {
    }

    /// Finalizes the instance.
    ~MulticastRecoveryFeedSettings()
    {
    }

    /// Re-initializes the instance as a copy of the other one. 
    MulticastRecoveryFeedSettings&
    operator =(
        const 
        MulticastRecoveryFeedSettings& other)
    {
        group().
            controlChange
            (
                "Multicast Recovery Feed Settings",
                &MulticastRecoveryFeedSettings::assignNoControl,
                *this,
                other
            );

        return *this;
    }
};

/// Serializes feed settings into string.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    const MulticastRecoveryFeedSettings&);

/// Serializes feed settings into string.
inline
std::string
toStr(
    const 
    MulticastRecoveryFeedSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

/// Collection of parameters affecting recovery feeds behavior. 
ONIXS_CMEMDH_LTWT_CLASS
TcpRecoveryFeedSettings
: public FeedSettingsBase
  <
    RecoveryFeedLayout::Enum
  >
{
    // Makes assignment more flexible. 
    friend
    ONIXS_CMEMDH_LTWT_CLASS_DECL
    (
        FeedSettings
    );

    typedef 
    FeedSettingsBase
    <
        RecoveryFeedLayout::Enum
    >
    Base;

    UInt32 connectionAttempts_;
    UInt32 connectionTimeout_;
    UInt32 sendTimeout_;

    void
    assignNoControl(
        const TcpRecoveryFeedSettings& other)
    {
        Base::assignNoControl(other);

        connectionAttempts_ = 
            other.connectionAttempts_;

        connectionTimeout_ = 
            other.connectionTimeout_;

        sendTimeout_ = 
            other.sendTimeout_;
    }

public:
    /// Initializes instance with default values. 
    /// 
    /// By default, feed A is used as the primary source 
    /// of market recovery data with fail-over to the feed B. 
    /// Heartbeats are expected within 2 seconds periodicity.
    TcpRecoveryFeedSettings(
        const SettingGroup* group = NULL)
        : Base(
            group, 
            RecoveryFeedLayout::
            FeedAOnly,
            2)
        , connectionAttempts_(3)
        , connectionTimeout_(500)
        , sendTimeout_(5000)
    {
    }

    /// Initializes the instance 
    /// as a copy of the other one. 
    TcpRecoveryFeedSettings(
        const 
        TcpRecoveryFeedSettings& other)
        : Base(
            static_cast
            <const Base&>
            (other))
        , connectionAttempts_(
            other.connectionAttempts_)
        , connectionTimeout_(
            other.connectionTimeout_)
        , sendTimeout_(
            other.sendTimeout_)
    {
    }

    /// Finalizes the instance. 
    ~TcpRecoveryFeedSettings()
    {
    }

    /// Number of times the Handler must try 
    /// recovering from the other feed if it 
    /// fails to recover from the primary one.
    /// 
    /// @note Default value is '3'. 
    UInt32 
    connectionAttempts() const
    {
        return connectionAttempts_;
    }

    /// Number of times the Handler must try 
    /// recovering from the other feed if it 
    /// fails to recover from the primary one.
    TcpRecoveryFeedSettings& 
    connectionAttempts(
        UInt32 attemptQty)
    {
        group().
            controlAssignment
            (
                "Connection Attempts", 
                connectionAttempts_,
                attemptQty
            );

        return *this;
    }

    /// Interval between the attempts to receive 
    /// missed packets via the TCP recovery feed if 
    /// previous attempt either failed or was rejected.
    ///
    /// Interval is measured in milliseconds. 
    ///
    /// @note Default value is '500'. 
    UInt32 
    connectionTimeout() const
    {
        return connectionTimeout_;
    }

    /// Interval between the attempts to receive 
    /// missed packets via the TCP recovery feed if 
    /// previous attempt either failed or was rejected.
    ///
    /// Interval is measured in milliseconds. 
    TcpRecoveryFeedSettings& 
    connectionTimeout(
        UInt32 connectionTimeout)
    {
        group().
            controlAssignment
            (
                "Connection Timeout",
                connectionTimeout_, 
                connectionTimeout
            );

        return *this;
    }

    /// Time limit for the send operation.
    ///
    /// Value is measured in milliseconds. 
    ///
    /// @note Default value is '5000'. 
    UInt32 
    sendTimeout() const
    {
        return sendTimeout_;
    }

    /// Time limit for the send operation.
    ///
    /// Value is measured in milliseconds. 
    TcpRecoveryFeedSettings& 
    sendTimeout(
        UInt32 sendTimeout)
    {
        group().
            controlAssignment
            (
                "Send Timeout",
                sendTimeout_, 
                sendTimeout
            );

        return *this;
    }

    /// Re-initializes the instance 
    /// as a copy of the other one. 
    TcpRecoveryFeedSettings& 
    operator =(
        const 
        TcpRecoveryFeedSettings& other)
    {
        group().
            controlChange
            (
                "TCP Recovery Feed Settings",
                &TcpRecoveryFeedSettings::assignNoControl,
                *this,
                other
            );

        return *this;
    }
};

/// Serializes feed settings into string.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    const TcpRecoveryFeedSettings&);

/// Serializes feed settings into string.
inline
std::string
toStr(
    const TcpRecoveryFeedSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

/// Defines feed layout alternates available 
/// for real-time feed like incremental one. 
ONIXS_CMEMDH_LTWT_STRUCT RealtimeFeedLayout
{
    /// Integral type used as basement for constants. 
    typedef UInt32 Base;

    enum Enum
    {
        /// Indicates only feed A is used as source for market data. 
        FeedAOnly,

        /// Indicates only feed B is used as source for market data. 
        FeedBOnly,

        /// Feed A is used as primary source of market data. If Handler
        /// detects absence of market data on feed A, it switches to 
        /// feed B to continue market data processing. Feed B is used 
        /// by Handler until market data absence is detected on it. In 
        /// that case Handler will switch back to feed A. In other words,
        /// this layout instructs Handler to cycle between feeds if data
        /// absence is detected starting from feed A.
        FeedAWithFailoverToFeedB,

        /// Feed B is used as primary source of market data. If Handler
        /// detects absence of market data on feed B, it switches to 
        /// feed A to continue market data processing. Feed A is used 
        /// by Handler until market data absence is detected on it. In 
        /// that case Handler will switch back to feed B. In other words,
        /// this layout instructs Handler to cycle between feeds if data
        /// absence is detected starting from feed B.
        FeedBWithFailoverToFeedA,

        /// Handler arbitrates between both feeds A and B. 
        BothFeedsWithArbitrage
    };
};

/// Appends string presentation of feed layout.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    RealtimeFeedLayout::Enum);

/// Returns string presentation of feed layout.
inline 
std::string
toStr(
    RealtimeFeedLayout::Enum layout)
{
    std::string str;
    
    toStr(str, layout);
    
    return str;
}

/// Collection of parameters affecting real-time feeds behavior. 
ONIXS_CMEMDH_LTWT_CLASS 
RealtimeFeedSettings
: public FeedSettingsBase
  <
    RealtimeFeedLayout::Enum
  >
{
    friend
    ONIXS_CMEMDH_LTWT_CLASS_DECL
    (
        FeedSettings
    );

    typedef 
    FeedSettingsBase
    <
        RealtimeFeedLayout::Enum
    >
    Base;

    UInt32 outOfOrderPacketMaxInterval_;
    UInt32 lostPacketWaitTime_;

    void
    assignNoControl(
        const RealtimeFeedSettings& other)
    {
        Base::assignNoControl(other);

        outOfOrderPacketMaxInterval_ = 
            other.outOfOrderPacketMaxInterval_;

        lostPacketWaitTime_ = 
            other.lostPacketWaitTime_;
    }

public:
    /// Initializes instance with default values. 
    ///
    /// By default, arbitrage between feeds A and B is done.
    /// Heartbeats are expected within 30 seconds periodicity.
    RealtimeFeedSettings(
        const SettingGroup* group = NULL)
      : Base(
          group, 
          RealtimeFeedLayout::
          BothFeedsWithArbitrage,
          30)
      , outOfOrderPacketMaxInterval_(3)
      , lostPacketWaitTime_(100000)
    {
    }

    /// Initializes the instance 
    /// as a copy of the other one. 
    RealtimeFeedSettings(
        const 
        RealtimeFeedSettings& other)
        : Base(
            static_cast
            <const Base&>
            (other))
        , outOfOrderPacketMaxInterval_(
            other.outOfOrderPacketMaxInterval_)
        , lostPacketWaitTime_(
            other.lostPacketWaitTime_)
    {
    }

    /// Finalizes the instance.
    ~RealtimeFeedSettings()
    {
    }

    /// Defines a threshold used by the Handler 
    /// while handling out-of-order incoming packets.
    ///
    /// Due to the unreliable nature of multicast, packets may be missed 
    /// or received in an order different from the expected. The Handler 
    /// uses the given parameter to establish a threshold for incoming 
    /// packets whose sequence numbers are greater than expected unless 
    /// the expected packets are received or recognized as lost. 
    /// 
    /// When the Handler receives a packet with the sequence number higher 
    /// than expected, it considers the incoming packet as out-of-order. It 
    /// puts the packet into an internal queue if its sequence number does 
    /// not exceed the established threshold. The threshold represents the 
    /// sum of the last accepted packet's sequence number and the value of 
    /// the given parameter. 
    /// 
    /// Packets are queued unless the expected ones are received, or their 
    /// sequence numbers exceed the threshold, or the time limit is reached. 
    /// If the incoming packet's sequence number exceeds the established 
    /// threshold, the Handler raises the gap event. 
    /// 
    /// If arbitrage between primary and secondary feeds is enabled, the 
    /// Handler does not trigger the gap event until incoming packets from 
    /// both feeds exceed the established threshold.
    ///
    /// @see 'lostPacketWaitTime' parameter for more information.
    ///
    /// @note The default value is '3'.
    UInt32 
    outOfOrderPacketMaxInterval() const
    {
        return outOfOrderPacketMaxInterval_;
    }

    /// Defines value of threshold used by the Handler 
    /// while handling out-of-order incoming packets.
    RealtimeFeedSettings& 
    outOfOrderPacketMaxInterval(
        UInt32 intervalLength)
    {
        group().
            controlAssignment
            (
                "Out Of Order Packet Max Interval",
                outOfOrderPacketMaxInterval_, 
                intervalLength
            );

        return *this;
    }

    /// Indicates the time limit for the Handler while waiting 
    /// for expected packets before they are considered lost.
    /// 
    /// When the Handler receives a packet with the sequence number greater 
    /// than expected, it considers the received data as out-of-order. The 
    /// Handler resumes normal data processing if it receives missing data 
    /// during the given time interval.
    /// 
    /// However, if expected packets aren't received for a predefined time 
    /// frame, the Handler considers expected data as lost and raises the 
    /// gap event. The given parameter defines a time interval the Handler 
    /// waits for expected packets.
    ///
    /// @note The given parameter is used in combination with the 
    /// 'outOfOrderPacketMaxInterval' parameter.
    ///
    /// @see 'outOfOrderPacketMaxInterval' parameter for more information.
    ///
    /// The time interval is measured in microseconds (usec).
    ///
    /// @note The default value is '100000' (100 milliseconds).
    UInt32 
    lostPacketWaitTime() const
    {
        return lostPacketWaitTime_;
    }

    /// Defines the time limit for the Handler while waiting 
    /// for expected packets before they considered as lost.
    RealtimeFeedSettings& 
    lostPacketWaitTime(
        UInt32 waitTime)
    {
        group().
            controlAssignment
            (
                "Lost Packet Wait Time",
                lostPacketWaitTime_, 
                waitTime
            );

        return *this;
    }

    /// Re-initializes the instance 
    /// as a copy of the other one. 
    RealtimeFeedSettings&
    operator =(
        const 
        RealtimeFeedSettings& other)
    {
        group().
            controlChange
            (
                "Realtime Feed Settings",
                &RealtimeFeedSettings::assignNoControl,
                *this,
                other
            );

        return *this;
    }
};

/// Serializes feed settings into string.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    const RealtimeFeedSettings&);

/// Serializes feed settings into string.
inline
std::string
toStr(
    const RealtimeFeedSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

/// To optimally service customers and meet regulatory requirements for 
/// out-of-region recovery capabilities and timelines, CME Group utilizes 
/// a two data center model comprised of a Primary and a Disaster Recovery 
/// (DR) data center. The given enumeration class defines available kinds
/// of the data centers.
ONIXS_CMEMDH_LTWT_STRUCT DataCenter
{
    /// Integral type used as basement for constants. 
    typedef UInt32 Base;

    /// To optimally service customers and meet regulatory requirements 
    /// for out-of-region recovery capabilities and timelines, CME Group 
    /// utilizes a two data center model comprised of a Primary and a 
    /// Disaster Recovery (DR) data center. The given enumeration class 
    /// defines available kinds of the data centers.
    enum Enum
    {
        /// Indicates the primary data center, 
        /// which houses all CME applications. 
        Primary,

        /// Indicates data center used in case of disaster. 
        DisasterRecovery
    };
};

/// Appends string presentation of the given data center.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    DataCenter::Enum);

/// Returns string presentation of feed layout.
inline 
std::string
toStr(
    DataCenter::Enum layout)
{
    std::string str;
    
    toStr(str, layout);
    
    return str;
}

/// The parameters affecting all feeds 
/// involved into market data processing. 
ONIXS_CMEMDH_LTWT_CLASS 
FeedSettings : public SettingGroup
{
    // To let assignment be controlled 
    // by the master container. 
    friend 
    ONIXS_CMEMDH_LTWT_CLASS_DECL
    (
        HandlerSettings
    );

    std::string configurationFile_;
    DataCenter::Enum dataCenter_;

    PacketSize packetMaxSize_;

    RealtimeFeedSettings incrementalFeeds_;

    MulticastRecoveryFeedSettings instrumentFeeds_;
    MulticastRecoveryFeedSettings snapshotFeeds_;
    MulticastRecoveryFeedSettings mboSnapshotFeeds_;

    TcpRecoveryFeedSettings historicalFeeds_;

    NetFeedEngine* engine_;

    // Casts the given instance to an 
    // instance of SettingGroup class. 
    const 
    SettingGroup& 
    group() const
    {
        return *this;
    }

    // Re-initializes the given instance
    // as a copy of the other one without
    // involving assignment control service. 
    void
    assignNoControl(
        const FeedSettings& other)
    {
        configurationFile_ = 
            other.configurationFile_;

        dataCenter_ = other.dataCenter_;

        packetMaxSize_ = 
            other.packetMaxSize_;

        incrementalFeeds_.
            assignNoControl(
                other.incrementalFeeds_);

        instrumentFeeds_.
            assignNoControl(
                other.instrumentFeeds_);

        snapshotFeeds_.
            assignNoControl(
                other.snapshotFeeds_);

        mboSnapshotFeeds_.
            assignNoControl(
                other.mboSnapshotFeeds_);

        historicalFeeds_.
            assignNoControl(
                other.historicalFeeds_);

        engine_ = other.engine_;
    }

    // Updates interfaces for all primary feeds 
    // without involving assignment control services. 
    void 
    assignFeedAInterfaces(
        const std::string& interfaces)
    {
        NifListSetting nifs;

        fromStr(nifs, interfaces);

        incrementalFeeds_.
            A().
            networkInterfaces().
            assignNoControl(nifs);

        instrumentFeeds_.
            A().
            networkInterfaces().
            assignNoControl(nifs);

        snapshotFeeds_.
            A().
            networkInterfaces().
            assignNoControl(nifs);

        mboSnapshotFeeds_.
            A().
            networkInterfaces().
            assignNoControl(nifs);

        historicalFeeds_.
            A().
            networkInterfaces().
            assignNoControl(nifs);
    }

    // Updates interfaces for all primary feeds 
    // without involving assignment control services. 
    void 
    assignFeedBInterfaces(
        const std::string& interfaces)
    {
        NifListSetting nifs;

        fromStr(nifs, interfaces);

        incrementalFeeds_.
            B().
            networkInterfaces().
            assignNoControl(nifs);

        instrumentFeeds_.
            B().
            networkInterfaces().
            assignNoControl(nifs);

        snapshotFeeds_.
            B().
            networkInterfaces().
            assignNoControl(nifs);

        mboSnapshotFeeds_.
            B().
            networkInterfaces().
            assignNoControl(nifs);

        historicalFeeds_.
            B().
            networkInterfaces().
            assignNoControl(nifs);
    }

    /// Loads connectivity parameters from the given configuration file. 
    void
    assignConnectivityConfiguration(
        const std::string& configurationFile, 
        DataCenter::Enum dataCenter)
    {
        configurationFile_ = 
            configurationFile;

        dataCenter_ = 
            dataCenter;
    }

public:
    /// Initializes the instance with the default values. 
    FeedSettings(
        SettingChangeController* 
        controller = NULL)
        : SettingGroup(controller)
        , dataCenter_(DataCenter::Primary)
        , packetMaxSize_(1420)
        , incrementalFeeds_(&group())
        , instrumentFeeds_(&group())
        , snapshotFeeds_(&group())
        , mboSnapshotFeeds_(&group())
        , historicalFeeds_(&group())
        , engine_(NULL)
    {
    }

    /// Initializes the instance 
    /// as a copy of the other one. 
    FeedSettings(
        const FeedSettings& other)
        : SettingGroup()
        , configurationFile_(
            other.configurationFile_)
        , dataCenter_(
            other.dataCenter_)
        , packetMaxSize_(
            other.packetMaxSize_)
        , incrementalFeeds_(
            other.incrementalFeeds_)
        , instrumentFeeds_(
            other.instrumentFeeds_)
        , snapshotFeeds_(
            other.snapshotFeeds_)
        , mboSnapshotFeeds_(
            other.mboSnapshotFeeds_)
        , historicalFeeds_(
            other.historicalFeeds_)
        , engine_(
            other.engine_)
    {
    }

    /// Path to the connectivity configuration file.
    const 
    std::string&
    connectivityConfigurationFile() const
    {
        return configurationFile_;
    }

    /// Identifies the data center whose parameters are to 
    /// be extracted from the connectivity configuration file.
    /// 
    /// The connectivity configuration file may not include
    /// attributes for all kinds of data centers. 
    DataCenter::Enum
    dataCenter() const 
    {
        return dataCenter_;
    }

    /// Path to the connectivity configuration file from which 
    /// to load feed connection settings. 
    /// 
    /// The given parameter allows retrieving connectivity settings
    /// from the connectivity configuration file published by CME
    /// instead of manual setup. 
    /// 
    /// \warning The given parameter has lower priority comparing 
    /// to feed connection settings. E.g., if connection parameters
    /// are manually set up for any of feeds, the Handler will use 
    /// those parameters to connect to or join multicast groups. 
    /// The given parameter value is ignored in such a case and thus 
    /// connectivity configuration is not loaded from the specified 
    /// file. 
    /// 
    /// For certain environments CME provides additional data 
    /// centers to be used in case of a disaster. The additional 
    /// parameter allows specifing whether to load connection 
    /// settings for either the primary or a disaster recovery 
    /// data center. 
    FeedSettings& 
    connectivityConfigurationFile(
        const std::string& configurationFile,
        DataCenter::Enum dataCenter = DataCenter::Primary)
    {
        group().
            controlChange
            (
                "Connectivity Configuration File",
                &FeedSettings::assignConnectivityConfiguration,
                *this,
                configurationFile, 
                dataCenter
            );

        return *this;
    }

    /// Specifies one or more network interfaces on which to 
    /// join multicast groups referring to primary (A) feeds.
    /// 
    /// Multiple interfaces can be specified using semi-colon 
    /// as a delimiter. 
    /// 
    /// The given member is kind of batch set-up. Manual 
    /// specification of network interfaces for a particular 
    /// feed is also possible through the corresponding 
    /// parameters. 
    FeedSettings& 
    feedANetworkInterfaces(
        const std::string& interfaces)
    {
        group().
            controlChange
            (
                "Feed A Network Interfaces for All Feeds",
                &FeedSettings::assignFeedAInterfaces,
                *this,
                interfaces
            );

        return *this;
    }

    /// Specifies one or more network interfaces on which to 
    /// join multicast groups referring to secondary (B) feeds.
    /// 
    /// Multiple interfaces can be specified using semi-colon 
    /// as a delimiter. 
    /// 
    /// The given member is kind of batch set-up. Manual 
    /// specification of network interfaces for a particular 
    /// feed is also possible through the corresponding 
    /// parameters. 
    FeedSettings& 
    feedBNetworkInterfaces(
        const std::string& interfaces)
    {
        group().
            controlChange
            (
                "Feed B Network Interfaces for All Feeds",
                &FeedSettings::assignFeedBInterfaces,
                *this,
                interfaces
            );

        return *this;
    }

    /// Max size for network packet transmitted by MDP.
    ///
    /// @note Default value is '1420'.
    PacketSize packetMaxSize() const
    {
        return packetMaxSize_;
    }

    /// Max size for network packet transmitted by MDP.
    FeedSettings& 
    packetMaxSize(
        PacketSize value)
    {
        group().
            controlAssignment
            (
                "Packet Max Size", 
                packetMaxSize_,
                value
            );

        return *this;
    }

    /// The settings related to incremental feeds. 
    const 
    RealtimeFeedSettings& 
    incrementalFeeds() const
    {
        return incrementalFeeds_;
    }

    /// The settings related to incremental feeds. 
    RealtimeFeedSettings& 
    incrementalFeeds()
    {
        return incrementalFeeds_;
    }

    /// The settings related to instrument feeds. 
    const 
    MulticastRecoveryFeedSettings& 
    instrumentFeeds() const
    {
        return instrumentFeeds_;
    }

    /// The settings related to instrument feeds. 
    MulticastRecoveryFeedSettings& 
    instrumentFeeds()
    {
        return instrumentFeeds_;
    }

    /// The settings related to snapshot feeds. 
    const 
    MulticastRecoveryFeedSettings& 
    snapshotFeeds() const
    {
        return snapshotFeeds_;
    }

    /// The settings related to snapshot feeds. 
    MulticastRecoveryFeedSettings& 
    snapshotFeeds()
    {
        return snapshotFeeds_;
    }

    /// The settings related to snapshot feeds. 
    const 
    MulticastRecoveryFeedSettings& 
    mboSnapshotFeeds() const
    {
        return mboSnapshotFeeds_;
    }

    /// The settings related to snapshot feeds. 
    MulticastRecoveryFeedSettings& 
    mboSnapshotFeeds()
    {
        return mboSnapshotFeeds_;
    }

    /// The settings related to historical (TCP recovery) feeds. 
    const 
    TcpRecoveryFeedSettings& 
    historicalFeeds() const
    {
        return historicalFeeds_;
    }

    /// The settings related to historical (TCP Recovery) feeds. 
    TcpRecoveryFeedSettings& 
    historicalFeeds()
    {
        return historicalFeeds_;
    }

    /// Instance of the Feed Engine to be used by the Handler.
    /// Null instance means no feed engine is yet defined. 
    NetFeedEngine* engine() const
    {
        return engine_;
    }

    /// Defines instance of the Feed Engine to be used by the Handler.
    FeedSettings&
    engine(
        NetFeedEngine* engine)
    {
        group().
            controlAssignment
            (
                "Feed Engine", 
                engine_, 
                engine
            );

        return *this;
    }

    /// Re-initializes the instance 
    /// as a copy of the other one. 
    FeedSettings&
    operator =(
        const FeedSettings& other)
    {
        group().
            controlChange
            (
                "Feed Settings",
                &FeedSettings::assignNoControl,
                *this, 
                other
            );

        return *this;
    }
};

/// Serializes feed settings into string.
ONIXS_CMEMDH_EXPORTED
void
toStr(
    std::string&, 
    const FeedSettings&);

/// Serializes feed settings into string.
inline
std::string
toStr(
    const FeedSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

/// Retrieves connection settings from the given connectivity 
/// configuration file for the given channel and fills correspondent 
/// parameters in the given FeedSettings instance. 
/// 
/// If the configuration file includes connectivity settings for 
/// both primary and disaster recovery data centers, the additional 
/// parameter allows to control which settings are to be extracted. 
ONIXS_CMEMDH_EXPORTED
void
connectivityFromConfiguration
(
    FeedSettings&, 
    const std::string&, 
    ChannelId, 
    DataCenter::Enum =
        DataCenter::Primary
);

ONIXS_CMEMDH_NAMESPACE_END