ReplicationMutableConfig (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

com.sleepycat.je.rep

## Class ReplicationMutableConfig

- java.lang.Object
- - com.sleepycat.je.rep.ReplicationMutableConfig

- All Implemented Interfaces:
    Serializable, Cloneable
  Direct Known Subclasses:
    ReplicationConfig

      public class ReplicationMutableConfig
      extends Object
      implements Cloneable, Serializable

  Specifies the attributes that may be changed after a `ReplicatedEnvironment` has been created. `ReplicationMutableConfig` is a parameter to `Environment.setMutableConfig(com.sleepycat.je.EnvironmentMutableConfig)` and is returned by `Environment.getMutableConfig()`.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DESIGNATED_PRIMARY` Identifies the Primary node in a two node group.
    `static String` | `ELECTABLE_GROUP_SIZE_OVERRIDE` An escape mechanism to modify the way in which the number of electable nodes, and consequently the quorum requirements for elections and commit acknowledgments, is calculated.
    `static String` | `HELPER_HOSTS` The string identifying one or more helper host and port pairs in this format:
    `static String` | `LOG_FLUSH_TASK_INTERVAL` The interval that JE HA will do a log buffer flush.
    `static String` | `NODE_PRIORITY` The election priority associated with this node.
    `static String` | `REPLAY_DB_HANDLE_TIMEOUT` The maximum amount of time that an inactive database handle is kept open during a replay of the replication stream.
    `static String` | `REPLAY_MAX_OPEN_DB_HANDLES` The maximum number of most recently used database handles that are kept open during the replay of the replication stream.
    `static String` | `RUN_LOG_FLUSH_TASK` If true, JE HA (replication) will flush all committed transactions to disk at the specified time interval.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReplicationMutableConfig()` Create a ReplicationMutableConfig initialized with the system default settings.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getConfigParam(String paramName)` Return the value for this parameter.
    `boolean` | `getDesignatedPrimary()` Determines whether this node is the currently designated Primary.
    `int` | `getElectableGroupSizeOverride()` Returns the value associated with the override.
    `String` | `getHelperHosts()` Returns the string identifying one or more helper host and port pairs in this format:
    `int` | `getNodePriority()` Returns the election priority associated with the node.
    `ReplicationMutableConfig` | `setConfigParam(String paramName, String value)` Set this configuration parameter with this value.
    `ReplicationMutableConfig` | `setDesignatedPrimary(boolean isPrimary)` If `isPrimary` is true, designate this node as a Primary.
    `ReplicationMutableConfig` | `setElectableGroupSizeOverride(int override)` Sets the size used to determine the number of electable nodes.
    `ReplicationMutableConfig` | `setHelperHosts(String hostsAndPorts)` Identify one or more helpers nodes by their host and port pairs in this format:
    `ReplicationMutableConfig` | `setNodePriority(int priority)` Sets the election priority for the node.
    `String` | `toString()` List the configuration parameters and values that have been set in this configuration object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DESIGNATED_PRIMARY

          public static final String DESIGNATED_PRIMARY

      Identifies the Primary node in a two node group. See the discussion of issues when configuring two node groups

      Name | Type | Mutable | Default
      "je.rep.designatedPrimary" | Boolean | Yes | False

      See Also:
        Constant Field Values

    - #### ELECTABLE_GROUP_SIZE_OVERRIDE

          public static final String ELECTABLE_GROUP_SIZE_OVERRIDE

      An escape mechanism to modify the way in which the number of electable nodes, and consequently the quorum requirements for elections and commit acknowledgments, is calculated. The override is accomplished by specifying the quorum size via this mutable configuration parameter.

      When this parameter is set to a non-zero value at a member node, the member will use this value as the electable group size, instead of using the metadata stored in the RepGroup database for its quorum calculations. This parameter's value should be set to the number of electable nodes known to be available. The default value is zero, which indicates normal operation with the electable group size being calculated from the metadata.

      Please keep in mind that this is an escape mechanism, only for use in exceptional circumstances, to be used with care. Since JE HA is no longer maintaining quorum requirements automatically, there is the possibility that the simple majority of unavailable nodes could elect their own Master, which would result in a diverging set of changes to the same environment being made by multiple Masters. It is essential to ensure that the problematic nodes are in fact down before making this temporary configuration change. See the discussion in Appendix: Managing a Failure of the Majority.

      Name | Type | Mutable | Default
      "je.rep.electableGroupSizeOverride" | Integer | Yes | 0

      See Also:
        `QuorumPolicy`, `Durability.ReplicaAckPolicy`, Constant Field Values

    - #### NODE_PRIORITY

          public static final String NODE_PRIORITY

      The election priority associated with this node. The election algorithm for choosing a new master will pick the participating node that has the most current set of log files. When there is a tie, the election priority is used as a tie-breaker to select amongst these nodes.

      A priority of zero is used to ensure that this node is never elected master, even if it has the most up to date log files. Note that the node still votes for a Master and participates in quorum requirements. Please use this option with care, since it means that some node with less current log files could be elected master. As a result, this node would be forced to rollback committed data and must be prepared to handle any `RollbackException` exceptions that might be thrown.

      Name | Type | Mutable | Default | Minimum | Maximum
      "je.rep.node.priority" | Integer | Yes | 1 | 0 | Integer.MAX_VALUE

      See Also:
        `RollbackException`, Constant Field Values

    - #### RUN_LOG_FLUSH_TASK

          public static final String RUN_LOG_FLUSH_TASK

      If true, JE HA (replication) will flush all committed transactions to disk at the specified time interval. This is of interest because the default durability for replicated transactions of `Durability.COMMIT_NO_SYNC`. The default for this behavior is true.

      When using `Durability.COMMIT_NO_SYNC`, continued activity will naturally cause the steady flush of committed transactions, but a pause in activity may cause the latest commits to stay in memory. In such a case, it is unlikely but possible that all members of the replication group have these last transactions in memory and that no members have persisted them to disk. A catastrophic failure of all nodes in the replication group would cause a loss of these transactions, in this unlikely scenario. This background flush task will reduce such a possibility.

      Note that enabling this feature when using `Durability.COMMIT_NO_SYNC`, does not constitute a guarantee that updates made by a transaction are persisted. For an explicit guarantee, transactions should use `Durability.COMMIT_SYNC` or `Durability.COMMIT_WRITE_NO_SYNC`. These more stringent, persistent Durability options can be set at the environment or per-transaction scope. Using one of these Durability settings for a given transaction will also flush all commits that occurred earlier in time.

      Name | Type | Mutable | Default
      "je.rep.runLogFlushTask" | Boolean | No | true

      See Also:
        Constant Field Values

    - #### LOG_FLUSH_TASK_INTERVAL

          public static final String LOG_FLUSH_TASK_INTERVAL

      The interval that JE HA will do a log buffer flush.

      Name | Type | Mutable | Default | Minimum | Maximum
      "je.rep.logFlushTaskInterval" | Duration | Yes | 5 min | 1 s | -none-

      See Also:
        Time Duration Properties, Constant Field Values

    - #### REPLAY_MAX_OPEN_DB_HANDLES

          public static final String REPLAY_MAX_OPEN_DB_HANDLES

      The maximum number of most recently used database handles that are kept open during the replay of the replication stream.

      Name | Type | Mutable | Default | Minimum | Maximum
      "je.rep.replayMaxOpenDbHandles" | Int | Yes | 10 | 1 | -none-

      Since:
        5.0.38
      See Also:
        Constant Field Values

    - #### HELPER_HOSTS

          public static final String HELPER_HOSTS

      The string identifying one or more helper host and port pairs in this format:

           hostname[:port][,hostname[:port]]*

      Name | Type | Mutable | Default
      "je.rep.helperHosts" | String | Yes | ""

      See Also:
        `setHelperHosts(java.lang.String)`, `getHelperHosts()`, Constant Field Values

    - #### REPLAY_DB_HANDLE_TIMEOUT

          public static final String REPLAY_DB_HANDLE_TIMEOUT

      The maximum amount of time that an inactive database handle is kept open during a replay of the replication stream. Handles that are inactive for more than this time period are automatically closed. Note that this does not impact any handles that may have been opened by the application.

      Name | Type | Mutable | Default | Minimum | Maximum
      "je.rep.replayOpenHandleTimeout" | Duration | No | 30 sec | 1 sec | -none-

      Since:
        5.0.38
      See Also:
        Time Duration Properties, Constant Field Values

  - ### Constructor Detail

    - #### ReplicationMutableConfig

          public ReplicationMutableConfig()

      Create a ReplicationMutableConfig initialized with the system default settings. Parameter defaults are documented with the string constants in this class.

  - ### Method Detail

    - #### setDesignatedPrimary

          public ReplicationMutableConfig setDesignatedPrimary(boolean isPrimary)

      If `isPrimary` is true, designate this node as a Primary. This setting only takes effect for electable nodes. The application must ensure that exactly one electable node is designated to be a Primary at any given time. Primary node configuration is only a concern when the group has two electable nodes, and there cannot be a simple majority. See the overview on configuring two node groups.
      Parameters:
        `isPrimary` - true if this node is to be made the Primary
      Returns:
        this

    - #### getDesignatedPrimary

          public boolean getDesignatedPrimary()

      Determines whether this node is the currently designated Primary. See the overview on issues around two node groups
      Returns:
        true if this node is a Primary, false otherwise.

    - #### getElectableGroupSizeOverride

          public int getElectableGroupSizeOverride()

      Returns the value associated with the override. A value of zero means that the number of electable nodes is determined as usual, that is, from the contents of the group metadata.
      Returns:
        the number of electable nodes as specified by the override
      See Also:
        `ELECTABLE_GROUP_SIZE_OVERRIDE`

    - #### setElectableGroupSizeOverride

          public ReplicationMutableConfig setElectableGroupSizeOverride(int override)

      Sets the size used to determine the number of electable nodes.
      Parameters:
        `override` - the number of electable nodes. A value of zero means that the number of electable nodes is determined as usual, that is, from the contents of the group metadata.
      Returns:
        this
      See Also:
        `ELECTABLE_GROUP_SIZE_OVERRIDE`

    - #### getNodePriority

          public int getNodePriority()

      Returns the election priority associated with the node.
      Returns:
        the priority for this node
      See Also:
        `NODE_PRIORITY`

    - #### setNodePriority

          public ReplicationMutableConfig setNodePriority(int priority)

      Sets the election priority for the node. The algorithm for choosing a new master will pick the participating node that has the most current set of log files. When there is a tie, the priority is used as a tie-breaker to select amongst these nodes.

      A priority of zero is used to ensure that a node is never elected master, even if it has the most current set of files. Please use this option with caution, since it means that a node with less current log files could be elected master potentially forcing this node to rollback data that had been committed.

      Parameters:
        `priority` - the priority to be associated with the node. It must be zero, or a positive number.
      See Also:
        `NODE_PRIORITY`

    - #### getHelperHosts

          public String getHelperHosts()

      Returns the string identifying one or more helper host and port pairs in this format:

           hostname[:port][,hostname[:port]]*

      The port name may be omitted if it's the default port.
      Returns:
        the string representing the host port pairs

    - #### setHelperHosts

          public ReplicationMutableConfig setHelperHosts(String hostsAndPorts)

      Identify one or more helpers nodes by their host and port pairs in this format:

           hostname[:port][,hostname[:port]]*

      If the port is omitted, the default port defined by XXX is used.
      Parameters:
        `hostsAndPorts` - the string representing the host and port pairs.
      Returns:
        this

    - #### setConfigParam

          public ReplicationMutableConfig setConfigParam(String paramName,
                                                String value)
                                                  throws IllegalArgumentException

      Set this configuration parameter with this value. Values are validated before setting the parameter.
      Parameters:
        `paramName` - the configuration parameter name, one of the String constants in this class
        `value` - the configuration value.
      Returns:
        this;
      Throws:
        `IllegalArgumentException` - if the paramName or value is invalid.

    - #### getConfigParam

          public String getConfigParam(String paramName)
                                throws IllegalArgumentException

      Return the value for this parameter.
      Parameters:
        `paramName` - a valid configuration parameter, one of the String constants in this class.
      Returns:
        the configuration value.
      Throws:
        `IllegalArgumentException` - if the paramName is invalid.

    - #### toString

          public String toString()

      List the configuration parameters and values that have been set in this configuration object.
      Overrides:
        `toString` in class `Object`

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.