Converting Existing Environments for Replication

JE HA environments log files contain information and data used only by replication. Non-replicated environments are lacking this information, so in order to use a previously-existing non-replicated environment in an HA application, it must undergo a one time conversion.


If you try to open a non-replicated environment as a replicated environment, the operation will throw an UnsupportedOperationException. This is the only way your code can tell if an environment needs to be converted.

You use the DbEnableReplication class to perform this one-time conversion. This class is particularly useful if you want to prototype a standalone transactional application, and then add in replication after the transactional application is working as desired.

The conversion process is one-way; once an environment directory is converted, the rules that govern ReplicatedEnvironment apply. This means the environment can no longer be opened for writes by a standalone Environment handle (however, it still can be opened by a standalone Environment handle in read-only mode).

Note that DbEnableReplication only adds a minimum amount of replication metadata. The conversion process is not in any way dependent on the size of the environment you are converting.

The converted environment can be used to start a new replication group. After conversion, the environment can be opened as a ReplicatedEnvironment. Additional nodes that join the group are then populated with data from the converted environment.

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

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

// Bring up additional nodes, which will be initialized from 
// nodeMars.
ReplicationConfig repConfig = new ReplicationConfig();
try {

    nodeVenus = new ReplicatedEnvironment(envDirVenus, 
} 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,