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

com.sleepycat.je.rep

## Class NetworkRestore

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

-     public class NetworkRestore
      extends Object

  Obtains log files for a Replica from other members of the replication group. A Replica may need to do so if it has been offline for some time, and has fallen behind in its execution of the replication stream.

  During that time, the connected nodes may have reduced their log files by deleting files after doing log cleaning. When this node rejoins the group, it is possible that the current Master's log files do not go back far enough to adequately sync * up this node. In that case, the node can use a `NetworkRestore` object to copy the log files from one of the nodes in the group. The system tries to avoid deleting log files that either would be needed for replication by current nodes or where replication would be more efficient than network restore.

  A Replica discovers the need for a NetworkRestore operation when a call to `ReplicatedEnvironment()` fails with a `InsufficientLogException`.

  A call to `NetworkRestore.execute()` will copy the required log files from a member of the group who owns the files and seems to be the least busy. For example:

        try {
           node = new ReplicatedEnvironment(envDir, envConfig, repConfig);
       } catch (InsufficientLogException insufficientLogEx) {

           NetworkRestore restore = new NetworkRestore();
           NetworkRestoreConfig config = new NetworkRestoreConfig();
           config.setRetainLogFiles(false); // delete obsolete log files.

           // Use the members returned by insufficientLogEx.getLogProviders() to
           // select the desired subset of members and pass the resulting list
           // as the argument to config.setLogProviders(), if the default selection
           // of providers is not suitable.

           restore.execute(insufficientLogEx, config);

           // retry
           node = new ReplicatedEnvironment(envDir, envConfig, repConfig);
       }

  See Also:
    Restoring Log Files

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `NetworkRestore()` Creates an instance of NetworkRestore suitable for restoring the logs at this node.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `execute(InsufficientLogException logException, NetworkRestoreConfig config)` Restores the log files from one of the members of the replication group.

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

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

- - ### Constructor Detail

    - #### NetworkRestore

          public NetworkRestore()

      Creates an instance of NetworkRestore suitable for restoring the logs at this node. After the logs are restored, the node can create a new `ReplicatedEnvironment` and join the group

  - ### Method Detail

    - #### execute

          public void execute(InsufficientLogException logException,
                     NetworkRestoreConfig config)
                       throws EnvironmentFailureException,
                              IllegalArgumentException

      Restores the log files from one of the members of the replication group.

      If `config.getLogProviders()` returns null, or an empty list, it uses the member that is least busy as the provider of the log files. Otherwise it selects a member from the list, choosing the first member that's available, to provide the log files. If the members in this list are not present in `logException.getLogProviders()`, it will result in an `IllegalArgumentException` being thrown. Exceptions handlers for `InsufficientLogException` will typically use `InsufficientLogException.getLogProviders()` as the starting point to compute an appropriate list, with which to set up the `config` argument.

      Log files that are currently at the node will be retained if they are part of a consistent set of log files. Obsolete log files are either deleted, or are renamed based on the the configuration of `config.getRetainLogFiles()`.

      Parameters:
        `logException` - the exception thrown by `ReplicatedEnvironment()` that necessitated this log refresh operation
        `config` - configures the execution of the network restore operation
      Throws:
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalArgumentException` - if the `config` is invalid
      See Also:
        `NetworkRestoreConfig`

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