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

com.sleepycat.je.rep.util

## Class ReplicationGroupAdmin

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

-     public class ReplicationGroupAdmin
      extends Object

  Administrative APIs for use by applications which do not have direct access to a replicated environment. The class supplies methods that can be used to list group members, remove members, update network addresses, and find the current master. Information is found and updated by querying nodes in the group. Because of that, ReplicationGroupAdmin can only obtain information when there is at least one node alive in the replication group.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReplicationGroupAdmin(String groupName, Set<InetSocketAddress> helperSockets)` Constructs a group admin object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ReplicationGroup` | `getGroup()` Returns the current composition of the group from the Master.
    `String` | `getGroupName()` Returns the name of the replication group.
    `Set<InetSocketAddress>` | `getHelperSockets()` Returns the helper sockets being used to contact a replication group member, in order to query for the information.
    `String` | `getMasterNodeName()` Returns the node name associated with the master
    `NodeState` | `getNodeState(ReplicationNode repNode, int socketConnectTimeout)` Returns the `state` of a replicated node and `state` of the application where the node is running in.
    `void` | `removeMember(String nodeName)` Removes this node from the group, so that it is no longer a member of the group.
    `String` | `transferMaster(Set<String> nodeNames, int timeout, TimeUnit timeUnit, boolean force)` Transfers the master state from the current master to one of the electable replicas supplied in the argument list.
    `void` | `updateAddress(String nodeName, String newHostName, int newPort)` Update the network address for a specified member of the replication group.

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

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

- - ### Constructor Detail

    - #### ReplicationGroupAdmin

          public ReplicationGroupAdmin(String groupName,
                               Set<InetSocketAddress> helperSockets)

      Constructs a group admin object.
      Parameters:
        `groupName` - the name of the group to be administered
        `helperSockets` - the sockets on which it can contact helper nodes in the replication group to carry out admin services.

  - ### Method Detail

    - #### getHelperSockets

          public Set<InetSocketAddress> getHelperSockets()

      Returns the helper sockets being used to contact a replication group member, in order to query for the information.
      Returns:
        the set of helper sockets.

    - #### getGroupName

          public String getGroupName()

      Returns the name of the replication group.
      Returns:
        the group name.

    - #### getMasterNodeName

          public String getMasterNodeName()
                                   throws UnknownMasterException,
                                          EnvironmentFailureException

      Returns the node name associated with the master
      Returns:
        the master node ID
      Throws:
        `UnknownMasterException` - if the master was not found
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.

    - #### removeMember

          public void removeMember(String nodeName)
                            throws UnknownMasterException,
                                   MemberNotFoundException,
                                   MasterStateException,
                                   EnvironmentFailureException

      Removes this node from the group, so that it is no longer a member of the group. When removed, it will no longer be able to connect to a master, nor can it participate in elections. If the node is a `Monitor` it will no longer be informed of election results. Once removed, a node cannot be added again to the group under the same node name.

      Ideally, the node being removed should be shut down before this call is issued.

      If the node is an active `Replica` the master will terminate its connection with the node and will not allow the replica to reconnect with the group, since it's no longer a member of the group. If the node wishes to re-join it should do so with a different node name.

      An active Master cannot be removed. It must first be shutdown, or transition to the `Replica` state before it can be removed from the group.

      `Secondary` nodes cannot be removed; they automatically leave the group when they are shut down or become disconnected from the master.

      Parameters:
        `nodeName` - identifies the node being removed from the group
      Throws:
        `UnknownMasterException` - if the master was not found
        `IllegalArgumentException` - if the type of the node is `SECONDARY`
        `MemberNotFoundException` - if the node denoted by `nodeName` is not a member of the replication group
        `MasterStateException` - if the member being removed is currently the Master
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
      See Also:
        Adding and Removing Nodes From the Group

    - #### getGroup

          public ReplicationGroup getGroup()
                                    throws UnknownMasterException,
                                           EnvironmentFailureException

      Returns the current composition of the group from the Master.
      Returns:
        the group description
      Throws:
        `UnknownMasterException` - if the master was not found
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs

    - #### getNodeState

          public NodeState getNodeState(ReplicationNode repNode,
                               int socketConnectTimeout)
                                 throws IOException,
                                        com.sleepycat.je.rep.utilint.ServiceDispatcher.ServiceConnectFailedException

      Returns the `state` of a replicated node and `state` of the application where the node is running in.
      Parameters:
        `repNode` - a ReplicationNode includes those information which are needed to connect to the node
        `socketConnectTimeout` - the timeout value for creating a socket connection with the replicated node
      Returns:
        the state of the replicated node
      Throws:
        `IOException` - if the machine is down or no response is returned
        `com.sleepycat.je.rep.utilint.ServiceDispatcher.ServiceConnectFailedException` - if can't connect to the service running on the replicated node

    - #### updateAddress

          public void updateAddress(String nodeName,
                           String newHostName,
                           int newPort)
                             throws EnvironmentFailureException,
                                    MasterStateException,
                                    MemberNotFoundException,
                                    ReplicaStateException,
                                    UnknownMasterException

      Update the network address for a specified member of the replication group. When updating the address of this target replication node, the node cannot be alive. One common use case is when the replication member must be moved to a new host, possibly because of machine failure.

      To make a network address change, take these steps:

      1. Shutdown the node that is being updated.
      2. Use this method to change the hostname and port of the node.
      3. Start the node on the new machine, or at its new port, using the new hostname/port. If the log files are available at the node, they will be reused. A network restore operation may need to be initiated by the application to copy over any needed log files if no log files are available, or if they have become obsolete.

      The address of a `NodeType.SECONDARY` node cannot be updated with this method, since nodes must be members but not alive to be updated, and secondary nodes are not members when they are not alive. To change the address of a secondary node, restart the node with the updated address.

      Parameters:
        `nodeName` - the name of the node whose address will be updated.
        `newHostName` - the new host name of the node
        `newPort` - the new port number of the node
      Throws:
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs
        `MasterStateException` - if the member being updated is currently the master
        `MemberNotFoundException` - if the node denoted by `nodeName` is not a member of the replication group
        `ReplicaStateException` - if the member being updated is currently alive
        `UnknownMasterException` - if the master was not found
      See Also:
        `DbResetRepGroup, which can be used in a related but different use case to copy and move a group.`

    - #### transferMaster

          public String transferMaster(Set<String> nodeNames,
                              int timeout,
                              TimeUnit timeUnit,
                              boolean force)
                                throws MasterTransferFailureException,
                                       UnknownMasterException

      Transfers the master state from the current master to one of the electable replicas supplied in the argument list. This method sends a request to the original master to perform the operation.
      Throws:
        `MasterTransferFailureException` - if the master transfer operation fails
        `UnknownMasterException` - if the master was not found
        `IllegalArgumentException` - if `nodeNames` contains the name of a node that is not electable
      See Also:
        `ReplicatedEnvironment.transferMaster(java.util.Set<java.lang.String>, int, java.util.concurrent.TimeUnit)`

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