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 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 pass 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.
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

DbResetRepGroup(File envHome, String groupName, String nodeName, String nodeHostPort)
Create a DbResetRepGroup object for this node.

Method Summary

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