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

com.sleepycat.je.rep.util

## Class DbResetRepGroup

- java.lang.Object
- - com.sleepycat.je.rep.util.DbResetRepGroup

-     public class DbResetRepGroup
      extends Object

  A utility to reset the members of a replication group, replacing the group with a new group consisting of a single new member as described by the arguments supplied to the utility.

  This utility is useful when a copy of an existing replicated environment needs to be used at a different site, with the same data, but with a different initial node that can be used to grow the replication group as usual. The utility can also be used to change the group name associated with the environment.

  The reset environment has a different identity from the environment before the reset operation although it contains the same application data. To avoid confusion, the reset environment is assigned a new internal unique id. The unique id is checked whenever nodes attempt to communicate with each other and ensure that all nodes in a group are dealing with the same data.

  The reset process is typically accomplished using the steps outlined below. It's good practice to back up your environment before running any utilities that modify an environment.

  1. Use `DbResetRepGroup` to reset an existing environment. `DbResetRepGroup` can be used as a command line utility, and must be executed locally on the host specified in the -nodeHostPort argument. The host must also contain the environment directory. Alternatively, `DbResetRepGroup` may be used programmatically through the provided APIs.
  2. Once reset, the environment can be opened with a `ReplicatedEnvironment`, using the same node configuration as the one that was passed in to the utility. No helper host configuration is needed. Since the group consists of a single node, it will assume the role of a Master, so long as it is created as an electable node.
  3. Additional nodes may now be created and can join the group as newly created replicas, as described in `ReplicatedEnvironment`. Since these new nodes are empty, they should be configured to use the new master as their helper node, and will go through the replication node lifecycle to populate their environment directories. In this case, there will be data in the converted master that can only be transferred to the replica through a file copy executed with the help of a `NetworkRestore`

  For example:

       // Run the utility on a copy of an existing replicated environment. Usually
       // this environment will have originated on a different node and its
       // replication group information will contain meta data referring to its
       // previous host. The utility will reset this metadata so that it has a
       // rep group (UniversalRepGroup) with a single node named nodeMars. The node
       // is associated with the machine mars and will communicate on port 5001.

       DbResetRepGroup resetUtility =
           new DbResetRepGroup(envDirMars,          // env home dir
                               "UniversalRepGroup", // group name
                               "nodeMars",          // node name
                               "mars:5001");        // node host,port
       resetUtility.reset();

       // Open the reset environment; it will take on the role of master.
       ReplicatedEnvironment nodeMars = new ReplicatedEnvironment(envDirMars, ...);
       ...
       // Bring up additional nodes, which will be initialized from
       // nodeMars. For example, from the machine venus you can now add a new
       // member to the group(UniversalRepGroup) as below.

       ReplicationConfig repConfig = null;
       try {
           repConfig = new ReplicationConfig("UniversalRepGroup", // groupName
                                             "nodeVenus",         // nodeName
                                             "venus:5008");       // nodeHostPort
           repConfig.setHelperHosts("mars:5001");

           nodeVenus = new ReplicatedEnvironment(envDirB, repConfig, envConfig);
       } catch (InsufficientLogException insufficientLogEx) {

           // log files will be copied from another node in the group
           NetworkRestore restore = new NetworkRestore();
           restore.execute(insufficientLogEx, new NetworkRestoreConfig());

           // try opening the node now that the environment files have been
           // restored on this machine.
           nodeVenus = new ReplicatedEnvironment(envDirVenus,
                                                 repConfig,
                                                 envConfig);
       }
       ...

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DbResetRepGroup(File envHome, String groupName, String nodeName, String nodeHostPort)` Create a DbResetRepGroup object for this node.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `main(String[] args)` Usage:
    `void` | `reset()` Replaces the existing group with the new group having a single new node as described by the constructor arguments.

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

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

- - ### Constructor Detail

    - #### DbResetRepGroup

          public DbResetRepGroup(File envHome,
                         String groupName,
                         String nodeName,
                         String nodeHostPort)

      Create a DbResetRepGroup object for this node.
      Parameters:
        `envHome` - The node's replicated environment directory. The directory must be accessible on this host.
        `groupName` - The name of the new replication group
        `nodeName` - The node's name
        `nodeHostPort` - The host and port for this node. The utility must be executed on this host.

  - ### Method Detail

    - #### main

          public static void main(String[] args)

      Usage:

           java -cp je.jar com.sleepycat.je.rep.util.DbResetRepGroup
             -h <dir>                          # environment home directory
             -groupName <group name>           # replication group name
             -nodeName <node name>             # replicated node name
             -nodeHostPort <host name:port number> # host name or IP address
                                                       and port number to use
                                                       for this node

    - #### reset

          public void reset()

      Replaces the existing group with the new group having a single new node as described by the constructor arguments.
      See Also:
        `DbResetRepGroup`

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