Receiving the status of tasks returning from the nodes

Deprecation notice: as of JPPF 5.1, this extension is deprecated and replaced with "Receiving the status of tasks dispatched to or returned from the nodes". Though It will continue to work until it is removed in the next version, it is strongly recommended that you upgrade to the new extension.

Each time a set of tasks returns from a node, the driver emits a notification which encapsulates information about the set of tasks, alongs with detailed information on each of the tasks it contains. To receive these notifications, you must write a listener which implements the TaskReturnListener interface, defined as:

public interface TaskReturnListener {
  // Called when a job dispatch returns from a node
  void tasksReturned(TaskReturnEvent event);
}

As we can see, the tasksReturned() method receives events of type TaskReturnEvent, defined as follows:

public class TaskReturnEvent extends EventObject {
  // Get the uuid of the job to which the tasks belong
  public String getJobUuid()

  // Get the name of the job to which the tasks belong
  public String getJobName()

  // Get the list of tasks that were returned
  public List<ServerTaskInformation> getReturnedTasks()

  // Get the reason why the set of tasks was returned by a node
  public JobReturnReason getReturnReason()

  // Get the information on the node from which the tasks returned
  public JPPFManagementInfo getNodeInfo()
}

The method getReturnedTasks() returns a list of ServerTaskInformation objects, providing details on individual tasks:

public class ServerTaskInformation implements Serializable {
  // Get the position of this task within the job submitted by the client
  public int getJobPosition()

  // Get the throwable raised during the processing of the task
  public Throwable getThrowable()

  // Get the number of times a dispatch of the task has expired
  public int getExpirationCount()

  // Get the maximum number of times the task can be resubmitted
  public int getMaxResubmits()

  // Get the number of times the task was resubmitted
  public int getResubmitCount()
}

The method getReturnReason() provides a high-level indication of why the tasks were returned, among the possible reasons defined in the JobReturnReason enum:

public enum JobReturnReason {
  // The tasks were normally processed by the node
  RESULTS_RECEIVED,

  // The processing of the tasks took longer than the specified dispatch timeout
  DISPATCH_TIMEOUT,

  // An error occurred in the node which prevented the normal execution of the tasks
  NODE_PROCESSING_ERROR,

  // An error occurred in the driver while processing the results returned by the node
  DRIVER_PROCESSING_ERROR,

  // The connection between node and server was severed before results could be returned
  NODE_CHANNEL_ERROR
}

Following is an example listener which prints out its events to the console:

public class MyTaskReturnListener implements TaskReturnListener {
  public MyTaskReturnListener() {
    // message displayed at driver startup time
    System.out.println("in MyTaskReturnListener()");
  }

  @Override
  public void tasksReturned(TaskReturnEvent event) {
    List<ServerTaskInformation> tasks = event.getReturnedTasks();
    System.out.printf(
      "tasksReturned() : name=%s, uuid=%s, reason=%s, node=%s, %d tasks=%s%n",
      event.getJobName(), event.getJobUuid(), event.getReturnReason(),
      event.getNodeInfo(), tasks.size(), tasks);
  }
}

and here is an example output:

tasksReturned() : name=my job, uuid=job_uuid, reason=RESULTS_RECEIVED,
node=JPPFManagementInfo[192.168.1.24:12001, type=node|MASTER, local=false, secure=false,
uuid=node_uuid], 1 tasks=[ServerTaskInformation[jobPosition=85, throwable=null, 
expirationCount=0, maxResubmits=1, resubmitCount=0]]

Lastly, there are two ways to integrate a TaskReturnListener with the JPPF driver:

1) Using the JPPFDriver API

This can be done by calling the method getTaskReturnManager() on the JPPFDriver singleton instance, from another driver plugin, add-on or extension. For instance, as in this driver startup class:

public class MyDriverStartup implements JPPFDriverStartupSPI {
  @Override
  public void run() {
    // get the object which manages task return listeners
    '''TaskReturnManager manager = JPPFDriver.getInstance().getTaskReturnManager();'''
    // register a new TaskReturnListener
    '''manager.addTaskReturnListener(new TaskReturnListener() {'''
      @Override
      public void tasksReturned(TaskReturnEvent event) {
        ...
      }
    });
  }
}

Note that you will need to have the jppf-server.jar file in your build path fir this code to compile.

2) Using the Service Provider Interface (SPI)

To register the TaskReturnListener as a standalone service, create a service definition file named "org.jppf.job.TaskReturnListener" in the "META-INF/services" directory. In this file, add, for each of your listener implementations, a line containing the fully qualified name of the implementation class. For instance, if we defined two implementations MyTaskReturnListener1 and MyTaskReturnListener2 in the test1 and test2 packages, respectively, then the service definiton file should contain:

test1. MyTaskReturnListener1
test2. MyTaskReturnListener2

Note that, to work with the SPI, each implementation must have a no-args constructor, whether implicit or explicit.