Administering the Replication Group

There are a series of administrative activities that an
application might want to take relative to a replication group.
These activities can be performed by electable or secondary nodes in the
replication group, or by applications that do not have access to
a replicated environment (in other words, utilities designed to
help administer and monitor the group). All of these functions
can be accessed using the ReplicationGroupAdmin class.

You instantiate an instance of the ReplicationGroupAdmin
class by providing it with the name of the replication group
that you want to administer, as well as a Set of
InetSocketAddress objects. The InetSocketAddress objects
are used as a list of helper hosts that the application can use
to perform administrative functions. For example:

Note

In order to obtain a ReplicationGroup object,
the process must be able to discover the current
Master. This means that the helper nodes you provide
when you instantiate the ReplicationGroupAdmin class
must be reachable and able to identify the current
Master. If they cannot, then these methods throw an
UnknownMasterException.

All of these methods return a set of ReplicationNode objects, which
you can then use to query for node information, such as its
name, the InetSocketAddress where the node is located,
and the node's type.

Adding and Removing Nodes from the Group

In order to add nodes to a replication group, you simply
start up a node and identify at least one helper node that
can identify the current Master to the new node. After the
new node has been populated with a current enough copy of
the data contained on the Master, the new node is
automatically a member of the replication group.

An electable node's status as a member of the group is persistent.
That is, it is a member of the group regardless of whether
it is running, and whether other nodes in the group can
reach it over the network. This means that for the purposes
of elections and message acknowledgements, the node counts
toward the total number of nodes that must respond and/or
participate in an event.

If, for example, you are using a durability guarantee that
requires all electable nodes in the replication group to acknowledge
a transaction commit on the Master, and if a node is down
or otherwise unavailable for some reason, then the commit
cannot complete on the Master because it will not receive
acknowledgements from all the electable nodes in the replication
group.

Similarly, elections for Masters require a bare majority of
electable nodes to participate in the election. If so many nodes are
shutdown or unavailable due to a network partition event
that a bare majority of electable nodes cannot be found to hold the
election, then your replication group can perform no write
activities. This situation persists until at least enough
nodes come back online to represent a bare majority of the
electable nodes belonging to the replication group.

For this reason, if you have an electable node that you intend to
shutdown for a long time, then you should remove that node
from the replication group. You do this using the
ReplicationGroupAdmin.removeMember() method. Note the
following rules when using this method:

For best results, shutdown the node before removing
it.

You use the node's name (not the host/port pair) to identify the node
you want to remove from the group. If the node name
that you specify is unknown to the replication
group, a MemberNotFoundException is thrown. If
it names a secondary node, an
IllegalArgumentException is thrown.

Once removed, the electable node can no longer connect to the
Master, nor can it participate in elections. If
you want to reconnect the node to the Master (that
is, you want to add it back to the replication group), you
will have to do so using a different node name than
the node was using when it was removed from the
group.

An active Master cannot be removed from the group. To
remove the active Master, either shut it down or wait
until it transitions to the Replica state.
If you attempt to remove an active Master, a
MasterStateException is thrown.