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

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

    Constructors
    Constructor and Description
    `Monitor(MonitorConfig monitorConfig)` Creates a monitor instance.
    `Monitor(ReplicationConfig monitorConfig)` Deprecated. As of JE 5, replaced by `Monitor(MonitorConfig)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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

          @Deprecated
          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`

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