com.sleepycat.je.rep.monitor
Class Monitor

java.lang.Object
  com.sleepycat.je.rep.monitor.Monitor

public class Monitor
extends Object

Provides a lightweight mechanism to track the current master node and the members of the replication group. The information provided by the monitor can be used to route update requests to the node that is currently the master and distribute read requests across the other members of the group.

The Monitor is typically run on a machine that participates in load balancing, request routing or is simply serving as a basis for application level monitoring and does not have a replicated environment. To avoid creating a single point of failure, an application may need to create multiple monitor instances, with each monitor running on a distinct machine.

Applications with direct access to a ReplicatedEnvironment can use its synchronous and asynchronous mechanisms for determining the master node and group composition changes. The Monitor class is not needed by such applications.

The Monitor generally learns about changes to group status through events issued by replication group members. In addition, the Monitor maintains a daemon thread which periodically pings members of the group so that the Monitor can proactively discover group status changes that occur when it is down or has lost network connectivity.

The following code excerpt illustrates the typical code sequence used to initiate a Monitor. Exception handling has been omitted to simplify the example.

 MonitorConfig monConfig = new MonitorConfig();
 monConfig.setGroupName("PlanetaryRepGroup");
 monConfig.setNodeName("mon1");
 monConfig.setNodeHostPort("monhost1.acme.com:7000");
 monConfig.setHelperHosts("mars.acme.com:5000,jupiter.acme.com:5000");

 Monitor monitor = new Monitor(monConfig);

 // If the monitor has not been registered as a member of the group,
 // register it now. register() returns the current node that is the
 // master.

 ReplicationNode currentMaster = monitor.register();

 // Start up the listener, so that it can be used to track changes
 // in the master node, or group composition. It can also be used to help
 // determine the electable nodes that are currently active and participating
 // in the replication group.
 monitor.startListener(new MyChangeListener());
 

See Also:

MonitorChangeListener, Writing Monitor Nodes, je.rep.quote Examples

Constructor Summary

Monitor(MonitorConfig monitorConfig)
Creates a monitor instance.

Monitor(ReplicationConfig monitorConfig)
Deprecated. As of JE 5, replaced by Monitor(MonitorConfig)

Method Summary

ReplicationGroup	getGroup() Returns the current composition of the group.
String	getGroupName() Returns the name of the group associated with the Monitor.
String	getMasterNodeName() Identifies the master of the replication group, resulting from the last successful election.
InetSocketAddress	getMonitorSocketAddress() Returns the socket used by this monitor to listen for group changes
String	getNodeName() Returns the group-wide unique name associated with the monitor
ReplicationNode	register() Registers the monitor with the group so that it can be kept informed of the outcome of elections and group membership changes.
void	shutdown() Release monitor resources and shut down the monitor.
void	startListener(MonitorChangeListener newListener) Starts the listener so it's actively listening for election results and broadcasts of replication group changes.

Methods inherited from class java.lang.Object

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

Constructor Detail

Monitor

public Monitor(ReplicationConfig monitorConfig)

Deprecated. As of JE 5, replaced by Monitor(MonitorConfig)

Deprecated as of JE5. Creates a monitor instance using a ReplicationConfig. Monitor-specific properties that are not available in ReplicationConfig use default settings.

Throws:

IllegalArgumentException - if an invalid parameter is specified.

Monitor

public Monitor(MonitorConfig monitorConfig)

Creates a monitor instance.

Parameters:

monitorConfig - configuration used by a Monitor

Throws:

IllegalArgumentException - if an invalid parameter is specified.

Method Detail

getGroupName

public String getGroupName()

Returns the name of the group associated with the Monitor.

Returns:

the group name

getNodeName

public String getNodeName()

Returns the group-wide unique name associated with the monitor

Returns:

the monitor name

getMonitorSocketAddress

public InetSocketAddress getMonitorSocketAddress()

Returns the socket used by this monitor to listen for group changes

Returns:

the monitor socket address

register

public ReplicationNode register()
                         throws EnvironmentFailureException

Registers the monitor with the group so that it can be kept informed of the outcome of elections and group membership changes. The monitor, just like a replication node, is identified by its nodeName. The Monitor uses the helper nodes to locate a master with which it can register itself. If the helper nodes are not available the registration will fail.

A monitor must be registered at least once in order to be informed of ongoing election results and group changes. Attempts to re-register the same monitor are ignored. Registration, once it has been completed successfully, persists beyond the lifetime of the Monitor instance and does not need to be repeated. Repeated registrations are benign and merely confirm that the current monitor configuration is consistent with earlier registrations of this monitor.

Returns:

the node that is the current master

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if the monitor has been shutdown, or no helper sockets were specified at Monitor initialization.

startListener

public void startListener(MonitorChangeListener newListener)
                   throws DatabaseException,
                          IOException

Starts the listener so it's actively listening for election results and broadcasts of replication group changes.

register() should be called before starting the listener. If the monitor has not been registered, it will not be updated, and its listener will not be invoked.

Once the registration has been completed, the Monitor can start listening even if none of the other nodes in the group are available. It will be contacted automatically by the other nodes as they come up.

If the group has a Master, invoking startListener results in a synchronous callback to the application via the MonitorChangeListener.notify(NewMasterEvent) method. If there is no Master at this time, the callback takes place asynchronously, after the method returns, when a Master is eventually elected.

Starting the listener will start the underlying ping thread, which proactively checks group status for changes that might have been missed when this Monitor instance has lost network connectivity or is down.

Parameters:

newListener - the listener used to monitor events of interest.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IOException - if the monitor socket could not be set up

IllegalArgumentException - if an invalid parameter is specified.

IllegalStateException - if the monitor has been shutdown, or a listener has already been established.

DatabaseException

getMasterNodeName

public String getMasterNodeName()
                         throws UnknownMasterException

Identifies the master of the replication group, resulting from the last successful election. This method relies on the helper nodes supplied to the monitor and queries them for the master. This method is useful when a Monitor first starts up and the Master needs to be determined. Once a Monitor is registered and the Listener has been started, it's kept up to date via events that are delivered to the Listener.

Returns:

the id associated with the master replication node.

Throws:

UnknownMasterException - if the master could not be determined from the set of helpers made available to the Monitor.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if the monitor has been shutdown.

getGroup

public ReplicationGroup getGroup()
                          throws UnknownMasterException,
                                 DatabaseException

Returns the current composition of the group. It does so by first querying the helpers to determine the master and then obtaining the group information from the master.

Returns:

an instance of RepGroup denoting the current composition of the group

Throws:

UnknownMasterException - if the master could not be determined from the set of helpers made available to the Monitor.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if the monitor has been shutdown.

DatabaseException

shutdown

public void shutdown()
              throws InterruptedException

Release monitor resources and shut down the monitor.

Throws:

InterruptedException