Management and monitoring from .Net

In the JPPF .Net bridge, the grid monitoring and management APIs rely on the underlying JMX (Java Management Extensions) layer provided by the JVM. Except for a few important points, these APIs are exactly the same as for a Java-based JPPF application. It is recommended to take a look at the related documentation before reading the next sections.

1 Using JMX reflective methods

The JPPF APIs based on JMX provide the ability to invoke methods on remote MBeans, by passing the appropriate parameters. This ability is available from the class JMXConnectionWrapper, mostly via its subclasses JMXDriverConnectionWrapper and JMXNodeConnectionWrapper, using their invoke() method:

public class JMXDriverConnectionWrapper {
  java.lang.Object invoke(java.lang.String mbeanName, java.lang.String methodName, 
                          java.lang.Object[] parameters, java.lang.String[] signature)
}

Note the last two parameters, of type java.lang.Object[] and java.lang.String[], respectively. They must be built explicitely, since the .Net bridge does not provide direct interoperability between these array types and the C# types object[] / string[]. Here, parameters represents the values of the parmaters for the method to invoke, and signature represents their Java type names.

For example, let's say we would like to dynamically change the priority of a job, which can be done by invoking the method updatePriority(java.lang.String jobUuid, java.lang.Integer priority) on the MBean interface DriverJobManagementMBean:

JPPFJob job = ...;
JMXDriverConnectionWrapper jmx = ...;
// provide the job uuid and the new priority = 4
java.lang.Object[] parameters = { job.getUuid(), new java.lang.Integer(4) };
java.lang.String[] signature = { "java.lang.String", "java.lang.Integer" };
string mbeanName = "org.jppf:name=jobManagement,type=driver";
jmx.invoke(mbeanName, "updatePriority", parameters, signature);

2 Static MBean proxies

Management operations are made easier by using proxies to the MBeans, where each proxy implements the declared MBean interface. The standard way in Java is to generate dynamic proxies from the JMX APIs, however this does not work in .Net. To work around this, JPPF provides static proxies which only rely on an instance of JMXConnectionWrapper.

The available static proxy classes, whch cover all JPPF built-in MBeans, are the following:

With a static proxy, our previous sample to update a job priority becomes much less cumbersome:

JPPFJob job = ...;
JMXDriverConnectionWrapper jmx = ...;
DriverJobManagementMBeanStaticProxy proxy = new DriverJobManagementMBeanStaticProxy(jmx);
proxy.updatePriority(job.getUuid(), new java.lang.Integer(4));

Please note that all static proxy classes inherit from the abstract class AbstractMBeanStaticProxy, which also provides a common API for the registration of MBean notification listeners.

Also notable is the fact that each proxy class provides a static method getMBeanName() which can be conveniently used to avoid hard-coding the name of each MBean.

3 JMX notification listeners

In the same way as for job listeners, JMX notification listeners must inherit from the abstract class BaseDotnetNotificationListener, defined as:

public abstract class BaseDotnetNotificationListener {
  // Handle a notification from a remote MBean
  public abstract void HandleNotification(Notification notification, object handback);
}

3.1 Direct notifications

The current implementation of the .Net bridge only allows to register notification listeners using one of the static proxy classes described in the previous section. To this effect, an extension method is provided for AbstractMBeanStaticProxy, and defined as follows:

public static class JPPFManagementExtensions {
  // Register a notification listener with the specified MBean
  public static void AddNotificationListener(this AbstractMBeanStaticProxy mbeanProxy, 
    BaseDotnetNotificationListener listener, object handback)
}

For example, let's define a listener which receives jobs life cycle notifications from the job management MBean defined in the remote driver:

<pre class="prettyprint lang-cs">
// This notification listener prints jobs life cycle events to the console
public class MyNotificationListener : BaseDotnetNotificationListener {
  // handle notification
  public override void HandleNotification(Notification notification, object handback) {
    // cast to a specific notification type
    JobNotification notif = notification as JobNotification;
    if (notif != null) {
      JobEventType type = notif.getEventType();
      // skip job updated notifications
      if (type != JobEventType.JOB_UPDATED) {
        JobInformation jobInfo = notif.getJobInformation();
        int n = jobInfo.getTaskCount();
        Console.Write("job '" + jobInfo.getJobName() + "' received " + type +
         " notification" + (n > 0 ? " for " + n + " tasks" : "") +
         ", handback = " + (handback != null ? "" + handback : "null"));
      }
    }
  }
}

To register this listener appropriately, we would proceed as follows:

JMXDriverConnectionWrapper jmx = ...;
AbstractMBeanStaticProxy jobProxy = new DriverJobManagementMBeanStaticProxy(jmx);
jobProxy.AddNotificationListener(new MyNotificationListener(), "job events handback");

3.2 Node notifications forwarded by the driver

To register a forwarding notification listener (which forwards nodes notifications via the JPPF driver), use the following extension method for JMXDriverConnectionWrapper:

public static class JPPFManagementExtensions {
  // Register a listener which forwards node notifications via the driver
  public static string RegisterFowrwardingNotificationListener(
    this JMXDriverConnectionWrapper jmx, NodeSelector selector, string mbeanName,
    BaseDotnetNotificationListener listener, object handback)
}

As an example, let's implement a notification listener which processes task completion notifications emitted by the NodeTaskMonitorMBean registered with each node:

public class MyTaskNotificationListener : BaseDotnetNotificationListener {
  // handle task completion notifications
  public override void HandleNotification(Notification notification, object handback) {
    JPPFNodeForwardingNotification fwdNotif =
      notification as JPPFNodeForwardingNotification;
    TaskExecutionNotification notif =
      fwdNotif.getNotification() as TaskExecutionNotification;
    // only handle JPPF built-in task completion notifications
    if ((notif != null) && !notif.isUserNotification()) {
      TaskInformation taskInfo = notif.getTaskInformation();
      string id = taskInfo.getId();
      if (id == null) id = "null id";
      Console.WriteLine("task '" + id + "' from job '" + taskInfo.getJobName() +
        "' has completed " + (taskInfo.hasError() ? "with error" : "successfully"));
    }
  }
}

We can then register this listener as follows:

JMXDriverConnectionWrapper jmx = ...;
// name of the node task monitor MBean
string mbeanName = JPPFNodeTaskMonitorMBeanStaticProxy.getMBeanName();
// only receive notifications from .Net-capable nodes
ExecutionPolicy dotnetPolicy = new Equal("jppf.dotnet.bridge.initialized", true);
NodeSelector selector = new ExecutionPolicySelector(dotnetPolicy);
// register the forwarding listener witht he driver
string listenerId = jmx.RegisterFowrwardingNotificationListener(
  selector, mbeanName, new MyTaskNotificationListener(), "task notification");
Console.WriteLine("added task notifications listener with id = " + listenerId);