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

com.sleepycat.je.rep.util

## Class DbEnableReplication

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

-     public class DbEnableReplication
      extends Object

  A utility to convert an existing, non replicated JE environment for replication. This is useful when the user wants to initially prototype and develop a standalone transactional application, and then add replication as a second stage.

  JE HA environment log files contain types of log records and metadata used only by replication. Non replicated environments are lacking that information and must undergo a one time conversion process to add that metadata and enable replication. The conversion process is one way. Once an environment directory is converted, the rules that govern `ReplicatedEnvironment` apply; namely, the directory cannot be opened by a read/write standalone `Environment`. Only a minimum amount of replication metadata is added, and the conversion process is not dependent on the size of the existing directory.

  The conversion process takes these steps:

  1. Use `DbEnableReplication` to convert an existing environment directory. `DbEnableReplication` can be used as a command line utility, and must be executed locally on the host which houses the environment directory. Alternatively, `DbEnableReplication` may be used programmatically through the provided APIs.
  2. Once converted, the environment directory may be treated as an existing master node, and can be opened with a `ReplicatedEnvironment`. No helper host configuration is needed.
  3. Additional nodes may 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 converted 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:

       // Create the first node using an existing environment
       DbEnableReplication converter =
           new DbEnableReplication(envDirMars,          // env home dir
                                   "UniversalRepGroup", // group name
                                   "nodeMars",          // node name
                                   "mars:5001");        // node host,port
       converter.convert();

       ReplicatedEnvironment nodeMars = new ReplicatedEnvironment(envDirMars, ...);

       // Bring up additional nodes, which will be initialized from
       // nodeMars.
       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
           nodeVenus = new ReplicatedEnvironment(envDirVenus,
                                                 repConfig,
                                                 envConfig);
       }
       ...

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `convert()` Modify the log files in the environment directory to add a modicum of replication required metadata.
    `static void` | `main(String[] args)` Usage:

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

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

- - ### Constructor Detail

    - #### DbEnableReplication

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

      Create a DbEnableReplication object for this node.
      Parameters:
        `envHome` - The node's environment directory
        `groupName` - The name of the new replication group
        `nodeName` - The node's name
        `nodeHostPort` - The host and port for this node

  - ### Method Detail

    - #### main

          public static void main(String[] args)

      Usage:

           java -cp je.jar com.sleepycat.je.rep.util.DbEnableReplication
             -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

    - #### convert

          public void convert()

      Modify the log files in the environment directory to add a modicum of replication required metadata.

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