path: root/lang/csharp/src/ReplicationConfig.cs

/*-
 * See the file LICENSE for redistribution information.
 *
 * Copyright (c) 2009, 2015 Oracle and/or its affiliates.  All rights reserved.
 *
 */
using System;
using System.Collections.Generic;
using System.Text;

namespace BerkeleyDB {
    /// <summary>
    /// A class representing configuration parameters for a
    /// <see cref="DatabaseEnvironment"/>'s replication subsystem.
    /// </summary>
    public class ReplicationConfig {

        /// <summary>
        /// Instantiate a new ReplicationConfig object with default
        /// configuration values.
        /// </summary>
        public ReplicationConfig() {
            AutoInit = true;
            Elections = true;
            RepmgrSitesConfig = new List<DbSiteConfig>();
        }

        #region Config Flags
        /// <summary>
        /// If true, the replication master sends groups of records to the
        /// clients in a single network transfer
        /// </summary>
        public bool BulkTransfer;
        /// <summary>
        /// If true, the client delays synchronizing to a newly declared
        /// master (defaults to false). Clients configured in this way
        /// remain unsynchronized until the application calls
        /// <see cref="DatabaseEnvironment.RepSync"/>. 
        /// </summary>
        public bool DelayClientSync;
        /// <summary>
        /// If true, replication only stores the internal information in-memory
        /// and cannot keep persistent state across a site crash or reboot. By
        /// default, it is false and replication creates files in the
        /// environment home directory to preserve the internal information. 
        /// This configuration flag can only be set before the
        /// <see cref="DatabaseEnvironment"/> is opened.
        /// </summary>
        public bool InMemory;
        /// <summary>
        /// If true, master leases are used for this site (defaults to
        /// false). 
        /// </summary>
        /// <remarks>
        /// Configuring this option may result in a 
        /// <see cref="LeaseExpiredException"/> when attempting to read entries
        /// from a database after the site's master lease has expired.
        /// </remarks>
        public bool UseMasterLeases;
        /// <summary>
        /// If true, the replication master automatically re-initializes
        /// outdated clients (defaults to true). 
        /// </summary>
        public bool AutoInit;
        /// <summary>
        /// If true, Berkeley DB method calls that would normally block while
        /// clients are in recovery will return errors immediately (defaults to
        /// false).
        /// </summary>
        public bool NoBlocking;
        /// <summary>
        /// If true, the Replication Manager observes the strict "majority"
        /// rule in managing elections, even in a group with only 2 sites. This
        /// means the client in a 2-site group is unable to take over as
        /// master if the original master fails or becomes disconnected. (See
        /// the Elections section in the Berkeley DB Reference Guide for more
        /// information.) Both sites in the replication group should have the
        /// same value for this parameter.
        /// </summary>
        public bool Strict2Site;
        /// <summary>
        /// If true, Replication Manager automatically runs elections to
        /// choose a new master when the old master appears to
        /// have become disconnected (defaults to true).
        /// </summary>
        public bool Elections;
        /// <summary>
        /// This flag is used to specify the preferred master site in a
        /// replication group operating in preferred master mode. A preferred
        /// master replication group must contain only two sites, with one site
        /// specified as the preferred master site and the other site specified
        /// as the client site. The preferred master site operates as the
        /// master site whenever possible.
        /// </summary>
        public bool PrefmasMaster;
        /// <summary>
        /// This flag is used to specify the client site in a replication group
        /// operating in preferred master mode. A preferred master replication
        /// group must contain only two sites, with one site specified as the
        /// preferred master site and the other site specified as the client
        /// site. The client site in a preferred master replication group takes
        /// over temporarily as master when the preferred master site is
        /// unavailable.
        /// </summary>
        public bool PrefmasClient;
        #endregion Config Flags

        #region Timeout Values
        private uint _ackTimeout;
        internal bool ackTimeoutIsSet;
        /// <summary>
        /// The amount of time the replication manager's transport function
        /// waits to collect enough acknowledgments from replication group
        /// clients, before giving up and returning a failure indication. The
        /// default wait time is 1 second.
        /// </summary>
        public uint AckTimeout {
            get { return _ackTimeout; }
            set {
                _ackTimeout = value;
                ackTimeoutIsSet = true;
            }
        }

        private uint _checkpointDelay;
        internal bool checkpointDelayIsSet;
        /// <summary>
        /// The amount of time a master site delays between completing a
        /// checkpoint and writing a checkpoint record into the log.
        /// </summary>
        /// <remarks>
        /// This delay allows clients to complete their own checkpoints before
        /// the master requires completion of them. The default is 30 seconds.
        /// If all databases in the environment, and the environment's
        /// transaction log, are configured to reside in-memory (never preserved
        /// to disk), then, although checkpoints are still necessary, the delay
        /// is not useful and should be set to 0.
        /// </remarks>
        public uint CheckpointDelay {
            get { return _checkpointDelay; }
            set {
                _checkpointDelay = value;
                checkpointDelayIsSet = true;
            }
        }

        private uint _connectionRetry;
        internal bool connectionRetryIsSet;
        /// <summary>
        /// The amount of time the replication manager waits before trying
        /// to re-establish a connection to another site after a communication
        /// failure. The default wait time is 30 seconds.
        /// </summary>
        public uint ConnectionRetry {
            get { return _connectionRetry; }
            set {
                _connectionRetry = value;
                connectionRetryIsSet = true;
            }
        }

        private uint _electionTimeout;
        internal bool electionTimeoutIsSet;
        /// <summary>
        /// The timeout period for an election. The default timeout is 2
        /// seconds.
        /// </summary>
        public uint ElectionTimeout {
            get { return _electionTimeout; }
            set {
                _electionTimeout = value;
                electionTimeoutIsSet = true;
            }
        }

        private uint _electionRetry;
        internal bool electionRetryIsSet;
        /// <summary>
        /// Configure the amount of time the replication manager waits
        /// before retrying a failed election. The default wait time is 10
        /// seconds. 
        /// </summary>
        public uint ElectionRetry {
            get { return _electionRetry; }
            set {
                _electionRetry = value;
                electionRetryIsSet = true;
            }
        }

        private uint _fullElectionTimeout;
        internal bool fullElectionTimeoutIsSet;
        /// <summary>
        /// An optional configuration timeout period to wait for full election
        /// participation the first time the replication group finds a master.
        /// By default this option is turned off and normal election timeouts
        /// are used. (See the Elections section in the Berkeley DB Reference
        /// Guide for more information.) 
        /// </summary>
        public uint FullElectionTimeout {
            get { return _fullElectionTimeout; }
            set {
                _fullElectionTimeout = value;
                fullElectionTimeoutIsSet = true;
            }
        }

        private uint _heartbeatMonitor;
        internal bool heartbeatMonitorIsSet;
        /// <summary>
        /// The amount of time the replication manager, running at a client
        /// site, waits for some message activity on the connection from the
        /// master (heartbeats or other messages) before concluding that the
        /// connection has been lost. When 0 (the default), no monitoring is
        /// performed.
        /// </summary>
        public uint HeartbeatMonitor {
            get { return _heartbeatMonitor; }
            set {
                _heartbeatMonitor = value;
                heartbeatMonitorIsSet = true;
            }
        }

        private uint _heartbeatSend;
        internal bool heartbeatSendIsSet;
        /// <summary>
        /// The frequency at which the replication manager, running at a master
        /// site, broadcasts a heartbeat message in an otherwise idle system.
        /// When 0 (the default), no heartbeat messages are sent. 
        /// </summary>
        public uint HeartbeatSend {
            get { return _heartbeatSend; }
            set {
                _heartbeatSend = value;
                heartbeatSendIsSet = true;
            }
        }

        private uint _leaseTimeout;
        internal bool leaseTimeoutIsSet;
        /// <summary>
        /// The amount of time a client grants its master lease to a master.
        /// When using master leases all sites in a replication group must use
        /// the same lease timeout value. There is no default value. If leases
        /// are desired, this method must be called prior to calling
        /// <see cref="DatabaseEnvironment.RepStartClient"/> or
        /// <see cref="DatabaseEnvironment.RepStartMaster"/>.
        /// </summary>
        public uint LeaseTimeout {
            get { return _leaseTimeout; }
            set {
                _leaseTimeout = value;
                leaseTimeoutIsSet = true;
            }
        }
        #endregion Timeout Values

        private uint _clockskewFast;
        private uint _clockskewSlow;
        internal bool clockskewIsSet;
        /// <summary>
        /// The value, relative to <see cref="ClockskewSlow"/>, of the fastest
        /// clock in the group of sites.
        /// </summary>
        public uint ClockskewFast { get { return _clockskewFast; } }
        /// <summary>
        /// The value of the slowest clock in the group of sites.
        /// </summary>
        public uint ClockskewSlow { get { return _clockskewSlow; } }
        /// <summary>
        /// Set the clock skew ratio among replication group members based on
        /// the fastest and slowest measurements among the group for use with
        /// master leases.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Calling this method is optional, the default values for clock skew
        /// assume no skew. The user must also configure leases via
        /// <see cref="UseMasterLeases"/>. Additionally, the user must also
        /// set the master lease timeout via <see cref="LeaseTimeout"/> and
        /// the number of sites in the replication group via
        /// <see cref="NSites"/>. These settings may be configured in any
        /// order. For a description of the clock skew values, see Clock skew 
        /// in the Berkeley DB Programmer's Reference Guide. For a description
        /// of master leases, see Master leases in the Berkeley DB Programmer's
        /// Reference Guide.
        /// </para>
        /// <para>
        /// These arguments can be used to express either raw measurements of a
        /// clock timing experiment or a percentage across machines. For
        /// instance a group of sites have a 2% variance, then
        /// <paramref name="fast"/> should be set to 102, and
        /// <paramref name="slow"/> should be set to 100. Or, for a 0.03%
        /// difference, you can use 10003 and 10000 respectively.
        /// </para>
        /// </remarks>
        /// <param name="fast">
        /// The value, relative to <paramref name="slow"/>, of the fastest clock
        /// in the group of sites.
        /// </param>
        /// <param name="slow">
        /// The value of the slowest clock in the group of sites.
        /// </param>
        public void Clockskew(uint fast, uint slow) {
            clockskewIsSet = true;
            _clockskewSlow = slow;
            _clockskewFast = fast;
        }

        private uint _nsites;
        internal bool nsitesIsSet;
        /// <summary>
        /// The total number of sites in the replication group.
        /// </summary>
        /// <remarks>
        /// <para>
        /// This setting is typically used by applications which use the
        /// Berkeley DB library "replication manager" support. (However, see
        /// also <see cref="DatabaseEnvironment.RepHoldElection"/>, the
        /// description of the nsites parameter.)
        /// </para>
        /// </remarks>
        public uint NSites {
            get { return _nsites; }
            set {
                _nsites = value;
                nsitesIsSet = true;
            }
        }
        private uint _priority;
        internal bool priorityIsSet;
        /// <summary>
        /// The database environment's priority in replication group elections.
        /// A special value of 0 indicates that this environment cannot be a
        /// replication group master. If not configured, then a default value
        /// of 100 is used.
        /// </summary>
        public uint Priority {
            get { return _priority; }
            set {
                _priority = value;
                priorityIsSet = true;
            }
        }

        private ReplicationViewDelegate replicationView;
        internal bool repViewIsSet;
        /// <summary>
        /// Create a replication view and specify the function to determine
        /// whether a database file is replicated to the local site.
        /// </summary>
        /// <remarks>
        /// If it is null, the replication view is a full view and all database
        /// files are replicated to the local site. Otherwise it is a partial
        /// view and only some database files are replicated to the local site.
        /// </remarks>
        public ReplicationViewDelegate ReplicationView {
            get { return replicationView; }
            set {
                repViewIsSet = true;
                replicationView = value;
            }
        }

        private uint _retransmissionRequestMin;
        private uint _retransmissionRequestMax;
        internal bool retransmissionRequestIsSet;
        /// <summary>
        /// The minimum number of microseconds a client waits before requesting
        /// retransmission.
        /// </summary>
        public uint RetransmissionRequestMin {
            get { return _retransmissionRequestMin; }
        }
        /// <summary>
        /// The maximum number of microseconds a client waits before requesting
        /// retransmission.
        /// </summary>
        public uint RetransmissionRequestMax {
            get { return _retransmissionRequestMax; }
        }
        /// <summary>
        /// Set a threshold for the minimum and maximum time that a client waits
        /// before requesting retransmission of a missing message.
        /// </summary>
        /// <remarks>
        /// <para>
        /// If the client detects a gap in the sequence of incoming log records
        /// or database pages, Berkeley DB waits for at least
        /// <paramref name="min"/> microseconds before requesting retransmission
        /// of the missing record. Berkeley DB doubles that amount before
        /// requesting the same missing record again, and so on, up to a
        /// maximum threshold of <paramref name="max"/> microseconds.
        /// </para>
        /// <para>
        /// These values are thresholds only. Replication Manager applications 
        /// use these values to determine when to automatically request 
        /// retransmission of missing messages. For Base API applications, 
        /// Berkeley DB has no thread available in the library as a timer, the 
        /// threshold is only checked when a thread enters the Berkeley DB
        /// library to process an incoming replication message. Any amount of
        /// time may have passed since the last message arrived and Berkeley DB
        /// only checks whether the amount of time since a request was made is 
        /// beyond the threshold value or not.
        /// </para>
        /// <para>
        /// By default the minimum is 40000 and the maximum is 1280000 (1.28
        /// seconds). These defaults are fairly arbitrary and the application
        /// likely needs to adjust these. The values should be based on expected
        /// load and performance characteristics of the master and client host
        /// platforms and transport infrastructure as well as round-trip message
        /// time.
        /// </para></remarks>
        /// <param name="min">
        /// The minimum number of microseconds a client waits before requesting
        /// retransmission.
        /// </param>
        /// <param name="max">
        /// The maximum number of microseconds a client waits before requesting
        /// retransmission.
        /// </param>
        public void RetransmissionRequest(uint min, uint max) {
            retransmissionRequestIsSet = true;
            _retransmissionRequestMin = min;
            _retransmissionRequestMax = max;
        }

        private uint _gbytes;
        private uint _bytes;
        internal bool transmitLimitIsSet;
        /// <summary>
        /// The gigabytes component of the byte-count limit on the amount of
        /// data that is transmitted from a site in response to a single
        /// message processed by
        /// <see cref="DatabaseEnvironment.RepProcessMessage"/>.
        /// </summary>
        public uint TransmitLimitGBytes { get { return _gbytes; } }
        /// <summary>
        /// The bytes component of the byte-count limit on the amount of data
        /// that is transmitted from a site in response to a single
        /// message processed by
        /// <see cref="DatabaseEnvironment.RepProcessMessage"/>.
        /// </summary>
        public uint TransmitLimitBytes { get { return _bytes; } }
        /// <summary>
        /// Set a byte-count limit on the amount of data that is 
        /// transmitted from a site in response to a single message processed by
        /// <see cref="DatabaseEnvironment.RepProcessMessage"/>. The limit is
        /// not a hard limit, and the record that exceeds the limit is the last
        /// record to be sent. 
        /// </summary>
        /// <remarks>
        /// <para>
        /// Record transmission throttling is turned on by default with a limit
        /// of 10MB.
        /// </para>
        /// <para>
        /// If both <paramref name="GBytes"/> and <paramref name="Bytes"/> are
        /// zero, then the transmission limit is turned off.
        /// </para>
        /// </remarks>
        /// <param name="GBytes">
        /// The number of gigabytes which, when added to
        /// <paramref name="Bytes"/>, specifies the maximum number of bytes that
        /// are sent in a single call to 
        /// <see cref="DatabaseEnvironment.RepProcessMessage"/>.
        /// </param>
        /// <param name="Bytes">
        /// The number of bytes which, when added to 
        /// <paramref name="GBytes"/>, specifies the maximum number of bytes
        /// that are sent in a single call to
        /// <see cref="DatabaseEnvironment.RepProcessMessage"/>.
        /// </param>
        public void TransmitLimit(uint GBytes, uint Bytes) {
            transmitLimitIsSet = true;
            _gbytes = GBytes;
            _bytes = Bytes;
        }

        private uint _inqmaxgbytes;
        private uint _inqmaxbytes;
        internal bool repmgrIncomingQueueMaxIsSet;
        /// <summary>
        /// The gigabytes component of the maximum amount of dynamic memory
        /// used by the Replication Manager incoming queue.
        /// </summary>
        public uint RepmgrIncomingQueueMaxGBytes { get { return _inqmaxgbytes; } }
        /// <summary>
        /// The bytes component of the maximum amount of dynamic memory
        /// used by the Replication Manager incoming queue.
        /// </summary>
        public uint RepmgrIncomingQueueMaxBytes { get { return _inqmaxbytes; } }
        /// <summary>
        /// Set a byte-count limit on the maximum amount of dynamic memory
        /// used by the Replication Manager incoming queue.
        /// </summary>
        /// <remarks>
        /// <para>
        /// By default, the Replication Manager incoming queue size has a
        /// limit of 100MB.
        /// </para>
        /// <para>
        /// If both <paramref name="GBytes"/> and <paramref name="Bytes"/> are
        /// zero, then the Replication Manager incoming queue size is limited
        /// by available heap memory.
        /// </para>
        /// </remarks>
        /// <param name="GBytes">
        /// The number of gigabytes which, when added to
        /// <paramref name="Bytes"/>, specifies the maximum amount of dynamic
        /// memory used by the Replication Manager incoming queue.
        /// </param>
        /// <param name="Bytes">
        /// The number of bytes which, when added to 
        /// <paramref name="GBytes"/>, specifies the maximum amount of dynamic
        /// memory used by the Replication Manager incoming queue.
        /// </param>
        public void RepmgrIncomingQueueMax(uint GBytes, uint Bytes) {
            repmgrIncomingQueueMaxIsSet = true;
            _inqmaxgbytes = GBytes;
            _inqmaxbytes = Bytes;
        }

        /// <summary>
        /// The delegate used to transmit data using the replication
        /// application's communication infrastructure.
        /// </summary>
        public ReplicationTransportDelegate Transport;

        /// <summary>
        /// Specify how master and client sites handle the acknowledgment of
        /// replication messages which is necessary for "permanent" records.
        /// The current implementation requires all sites in a replication group
        /// to configure the same acknowledgement policy. 
        /// </summary>
        /// <seealso cref="AckTimeout"/>
        public AckPolicy RepMgrAckPolicy;

        /// <summary>
        /// A list of site configurations.
        /// </summary>
        public List<DbSiteConfig> RepmgrSitesConfig;
    }
}