Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 following code excerpt illustrates the typical code sequence used to initiate a Monitor. Exception handling has been omitted to simplify the example.

     ReplicationConfig monConfig = new ReplicationConfig();
     monConfig.setGroupName("PlanetaryRepGroup");
     monConfig.setNodeName("mon1");
     monConfig.setNodeType(NodeType.MONITOR);
     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, `NodeType.MONITOR`, je.rep.quote Examples

Constructor Summary
`Monitor(ReplicationConfig monitorConfig)` Creates a monitor instance using the config object.

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 sock 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 about 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)

  Creates a monitor instance using the config object. The `monitorConfig` must be initialized with the following configuration properties:
  - The `GroupName` of the replication group being monitored.
  - The (group wide) unique `NodeName` associated with this monitor node.
  - The `NodeType` must be set to `NodeType.Monitor`
  - The `NodeHost` identifying the hostname and port on which the monitor can be contacted.
  - The `HelperHosts` identifying the list of helpers the monitor can contact to register itself so it can receive notifications from the group when there is a change in masters.

  Parameters:
    `monitorConfig` - contains the monitor configuration initialized as described above.
  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 sock 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 about 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, if it needs to be kept up to date about 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.

  The Monitor must have been previously registered with the replication group via the `register()` method so that other nodes in the group are aware of it and can keep it current. If the monitor has not been registered, it will not be updated, that is, its listener will not be invoked. The registration needs to be done exactly once.

  Once the registration has been completed, the Monitor can start listening even when none of the other nodes in the group are available. It will be contacted automatically by the other nodes when they come up and hold a successful election.

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

  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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2004-2010 Oracle. All rights reserved.