C H A P T E R  5

Manipulating the Cluster Using the NMA

The Node Management Agent (NMA) exposes methods for causing a switchover and manipulating the retry count for processes and process groups monitored by the Daemon Monitor.

This chapter contains the following sections:


Using the NMA to Initiate a Switchover

Methods of the CmmMasterNodeMBean can be used to check whether a switchover is possible, initiate the switchover, and then gauge the success of the switchover. The switchover is performed by the Cluster Membership Manager (CMM).

Because it is possible to set a timeout value for CMM operations, it is also possible that CMM operations might not be completed during the time allowed. If the timeout value is too short, some or all CMM operations will fail. For more information about this CMM behavior, see the cmm_connect3CMM man page.



Note - To disable the ability to perform remote operations on a cluster, set the com.sun.nhas.ma.operation.flag property in nma.properties to false.



Checking Whether the Netra HA Suite Software Is Ready for Switchover

To check whether a switchover is possible, invoke the isSwitchOverReady method. The isSwitchOverReady method takes no parameters, and returns a Boolean value.



Note - Even if the isSwitchOverReady method returns true, this does not guarantee that switchover will succeed. Switchover might not succeed, for example, if cluster readiness changes between the time when the isSwitchOverReady is invoked and the switchOver method is invoked.



Initiating a Switchover

To initiate a switchover, invoke the switchOver method. The switchOver method takes no parameters, and returns a void. Note that if this method is invoked using the floating external address the connection to the NMA might be broken prematurely and the switchOver method will never finish executing. Write code to detect and handle this eventuality.

Example of Switchover Using an HTTP Connector Client

The NmaSwitchover class, the code of which is listed below, can be used to provoke a switchover of the current master node. The mechanism used below (the invoke() method of the HTTPConnectorClient class) can be used to invoke the methods of the NMA MBeans.


EXAMPLE 5-1   NmaSwitchover.java 
// java import
//
import java.net.InetAddress;
 
// jmx import
//
import javax.management.ObjectName;
import javax.management.MBeanException;
 
// jdmk import
//
import com.sun.jdmk.TraceManager;
import com.sun.jdmk.comm.HttpConnectorClient;
import com.sun.jdmk.comm.HttpConnectorAddress;
import com.sun.jdmk.comm.CommunicationException;
import com.sun.jdmk.comm.UnauthorizedSecurityException;
 
/**
 * This java client uses an HTTP connector client to establish a 
connection
 * to the NMA and perform a mastership switchover.
 *
 * To compile the client:
 *
 * javac NmaSwitchover.java
 *
 * Note: First ensure that the jar files specified in the chapter 
 * 'Configuration Files, Dependencies and Requirements' of the
 * "Netra High Availability Suite Foundation Services 2.1 6/03
 * NMA Programming Guide" are in your CLASSPATH.
 *
 * To run the client:
 *
 * java NmaSwitchover <domain_name> <master_IP_address> 
 * <HttpConnectorServer_port> 
 *    
 * For example:  java NmaSwitchover cluster_8 10.8.1.18 8081          
 *
 * Note: This example must be run on a machine with access to the 
 * cluster, for example, the cluster install server.
 *
 */
public class NmaSwitchover {
 
  public static void main(String argv[]) {
 
	try {
	    
	    /**
	    * Debug
	    * To activate the debug or trace mechanism from the
	    * command line, use the syntax: 
             java -DLEVEL_DEBUG NmaSwitchover <arguments>
	    * or: 
           * java -DLEVEL_TRACE NmaSwitchover <arguments>
	    *
	    * For example: 
	    * java -DLEVEL_DEBUG NmaSwitchover cluster_6 10.6.1.1 8081
	    *
	    */
	    
	    TraceManager.parseTraceProperties();
 
	    // Set the domain name of the cluster
	    //	    
	    String domain = "DefaultDomain";
	    if (argv.length >=1) domain = argv[0];
	    
	    // Set the host name of the remote MBean server.
	    //
	    String agentHost = InetAddress.getLocalHost().getHostName();
	    if (argv.length >= 2) agentHost = argv[1];
 
	    // Set the port number of the remote connector server.
	    //
	    int agentPort = 8081;
	    if (argv.length >= 3) 
	        agentPort = Integer.decode(argv[2]).intValue();
	    
	    System.out.println(">>> Connecting to " + agentHost +
			       " using port number " + agentPort);
 
	    // Set up the HTTP Connector Client.
	    //
	    HttpConnectorClient connector = new HttpConnectorClient();
	    try {
	      // Initialize communication with the remote MBean server.
	      //
       HttpConnectorAddress hca = 
       	     new HttpConnectorAddress(agentHost,agentPort);
       connector.connect(hca);
       } catch (IllegalArgumentException e)
	     {
	     System.out.println("Connection exception! " + 
	           e.getMessage());
	     } catch (CommunicationException e)
	     {
	       System.out.println("Connection exception! " + 
	           e.getMessage());
	     } catch (UnauthorizedSecurityException e)
	     {
	       System.out.println("Connection exception! " + 
	           e.getMessage());
	     }
 
	     String[] iargs = {};
	     String[] isig = {};
	    
	     String instanceName = domain + 
	        ".master:nhas-object=cluster_node";
	     ObjectName node = new ObjectName(instanceName);
      // Invoke the isSwitchOverReady() method to check that the
      // cluster is in a condition to support switchover successfully.
      // If this method returns true, invoke the switchover method.
      // Note that this does not guarantee that the switchover 
operation
      // will be successfully invoked, because the readiness of the
      // cluster may change before the switchover can be performed.
      // 
	    try {
	      if (connector.invoke(node, "isSwitchOverReady", 
	          	iargs, isig).equals(new Boolean(true))) 
	      {
         System.out.println("Performing switchover");
	        // Switchover
	        //
	        connector.invoke(node, "switchOver", iargs, isig);
        } else
	      {
	        System.out.println("Cluster not ready for switchover");
	      }
	    } catch (MBeanException e)
	    {
	      System.out.println("Got an exception invoking switchover! 
" +
	      e.getTargetException().getMessage());
	    }
	    
	    // Terminate communication with the remote MBean server.
	    //
	    connector.disconnect();
 
	    // Exit program
	    //
	    System.exit(0);
 
	} catch (Exception e) {
	    System.out.println("Got an exception !" + e.getMessage());
	    e.printStackTrace();
	    System.exit(1);
	    }
   }
 }

Getting the CMM Status of All Cluster Nodes

To get the CMM status of all cluster nodes, invoke the getAllNodeInfo method. The getAllNodeInfo method takes no parameters, and returns a CmmMemberInfo[].


Manipulating Daemon Monitor Retry Settings

The Daemon Monitor controls groups of processes and attempts to restart these processes if they fail. The number of times that the Daemon Monitor attempts to restart a group of failed processes can be set using the updateMaxRetryCount method of the PmdNameTagStatisticsMBean. When this method is invoked, the current count of the number of times that the Daemon Monitor has attempted to restart the process group is reset. When a group of processes has been successfully restarted, invoke the resetRetryCount method to ensure that the stipulated number of retries are attempted if the process group fails again.