Task documentation

• Provide a proper name to your task This will be used in Task View, by the interpreter to execute your tasks, by documentation in general to refer to your task ...
• Provide javadoc comments This is used to generate the Java API, see http://java.sun.com/j2se/javadoc/writingdoccomments/
• Provide jtags This is used to generate the URM, see http://herschel.be/twiki/bin/view/Hcss/DmChapter10#JTags
• Register your task in the proper categories This is used in the Task View's tree, see http://www.herschel.be/twiki/bin/view/Hcss/UrmCategories
• Document your task parameters This is used to generate default documentation for print _taskname_ and print _taskname.paramname_ , and in the GUI for parameter labels' tooltips.
• Use a doc static member This is used in the Task View to generate tooltips, as output for print _taskname.__doc__, will be used in the future for code completion

How to fill the doc static member

From Dive Into Python: Many Python IDEs use the doc string to provide context-sensitive documentation, so that when you type a function name, its doc string appears as a tooltip. This can be incredibly helpful, but it's only as good as the doc strings you write._

Task provides a default signature string (Task#getSignatureString()) that is either extracted from your doc string or generated from the current signature of the task. This string is better than nothing, but the task framework is not rich enough to be able to provide the best string possible, only the task creator can. While for Python functions, it is enough with a one line explanation and futher into after a blank line (see http://docs.python.org/tutorial/controlflow.html#SECTION006750000000000000000), the format we use for tasks differs: * 1st line signature string * 2nd line typically blank * 3rd and following explanation and further info.

A sample doc string follows

• Support the developer in providing easy syntax to handle data via task parameters.

<-- 

 Set ALLOWTOPICCHANGE = RegisteredUsersGroup, TWikiAdminGroup
 
-->

Creating the Average task

Running the task in the HIPE Console view

# Execute the task and get the result avg.execute()

Writing a Java task

How do tasks help?

• Command line help, exposing available algorithms and how they should be called.
• Integration in HIPE: you can register a task to be listed in HIPE, where it gets a standard graphical interface.
• Checking of input parameters.
• Recording of history.
• A common look-and-feel for the graphical interface.
• Re-usability: tasks are the building blocks of pipelines, and complex tasks can be composed of other tasks.
• Modifiability: a task defines how to execute the internal algorithm, how to provide inputs and to get outputs. You can modify the internal algorithm or even change it altogether, as long as input and output parameters remain the same.

Writing a task in Jython

The Jython function: average(table)

Writing Tasks

Tasks are data processors. You can use a task to manipulate a data product, such as an image, or to convert data from one kind into another, for instance extracting a spectrum from a cube.

If you have an algorithm that does data processing, you can turn it into a task whether it is written in Jython or in Java. This topic explains how this is done.

How does the Task Framework help?

The Task framework provides functionality in a Task superclass, which can be reused by the user's tasks. The Task superclass provides, for example:

• Command line help, exposing available algorithms and how they should be called
• Integration in HIPE: Tasks can be accessed and run using the HIPE GUI
• Input parameter checking
• History recording
• A common look and feel or the user (fixed methods to execute, to get the output, etc.)
• Re-usability: Tasks are the building blocks of pipelines, and complex tasks can be composed of other tasks
• Modifiability: Because Task defines how to execute the algorithm and how to get the output, etc, the user can modify the algorithm, or change one algorithm for another, as long as the established Task rules are still followed

This has some similarities to the Interactive Reduction and Analysis Facility (IRAF) where tasks/programs have a set of their own parameters and help. In IRAF, the history is placed in the header information of the files worked on.

A function is therefore placed within a task and can be adjusted and changed and replaced within the task so long as the parameters for input and output remain the same. This makes the task concept ideal for users who are creating scripts for other users. You get the consistency checking, help and history recording in a consistent fashion for a little bit of extra packaging.

Tasks can be used anywhere in the DP environment: From the Jython command line in HIPE, the Quick-Look Analysis (QLA) environment and in the pipelines (Standard Product Generation).

How To Write a Task in Jython

This section describes how to turn a Jython algorithm into a Task. This is done with an example of a Jython "algorithm" that calculates an average. This "algorithm" is coded in a Jython function. It will be shown how to turn this function into a task.

We start by giving the example function.

A Jython function: average(table)

The following is a Jython function that takes a table and calculates the average of each of the columns.

# Import data structures from java classes
from herschel.ia.numeric.all import *
from herschel.ia.dataset.all import *

#--------------------------------------------------
# average function
# Takes a TableDataSet as input
# Returns a Double1d (1D array of real numbers)
# in which each row is the average of the values
# in the input table columns
#--------------------------------------------------
#routine for calculating the average
def average(table):
    columns = table.columnCount
    divider = 1.0 / columns
    result = Double1d(table.rowCount)
    for column in range(columns):
        result.add(table.getColumn(column).data)
    return result.multiply(divider)

You can use the following functions to try it out:

# Function for creating a table with some test data
# The table will be like this:
# 0 1 2 3 4 5
# 1 2 3 4 5 6
# 2 3 4 5 6 7
# 3 4 5 6 7 8
# 4 5 6 7 8 9
def createTable():
    #create array x (0.0, 1.0, 2.0, 3.0, 4.0)
    x = Double1d.range(5)
    columns = 5
    #create an empty table with a name
    table = TableDataset(description = "a test table")
    #iterate for the the number of columns to fill up the table
    for column in range(0,columns):
        table["%i" % column] = Column(x)
        x = x + 1
    #return the result, a table called 'table'
    return table

# Function for executing the method
def testAverage():
    # create the table
    table = createTable()
    # get the average and put it into an array called 'result'
    result = average(table)
    # print the result
    print 'result', result

The result of typing testAverage() on the Console view of HIPE is:

result [2.0,3.0,4.0,5.0,6.0]

Creating the Task: Average

To turn our average algorithm into a task we need to wrap the algorithm into a piece of code which adapts it to form a task. Our current function has no input parameters (it is a parameterless execute method). We need to wrap it so that we have the appropriate input parameters (so it becomes a parameterized method).

We will name the task itself Average (a task is a class, it is callable from the command line, and by convention class names are capitalized nouns). In our Average class we have no needs other than setting up a signature and calling the average function as part of its execution.

Every Task must extend the JTask, so the first step in creating our task class is to subclass JTask.

If you check the chapter about writing a Task in Java, you will see that the class in Jython looks slightly different. This is due to differences in implementation details between Jython and Java, and cannot be avoided. To extend JTask, only the following is required:

# Import task framework classes.
from herschel.ia.task.all import *
# Import data structures from java classes needed
from herschel.ia.dataset.all import *
from herschel.ia.numeric.all import *
# Import our algorithm
from average import average

class Average(JTask):
   def __init__(self):
       # This is the constructor of the Task. Initialize the superclass:
       JTask.__init__(self, "averageTask")

       # Define the *Signature* using calls to the addTaskParameter method
       # The following lines define one TableDataset input parameter, called table
       # And one output parameter of type Double1d.
       p = TaskParameter("table",valueType = TableDataset, mandatory = 1)
       self.addTaskParameter(p)
       p = TaskParameter("result",valueType = Double1d, type = OUT)
       self.addTaskParameter(p)

   # Here we define the execute method:
   def execute(self):
       # Define the code to be *executed*: Call our average method here
       # The input parameter 'table' is passed as the argument of the function
       self.result = average(self.table) 

These steps are explained in greater detail in the next sections.

About the import statements in the above example, the following: The task framework classes are the "standard" definitions allowing import of a task definition. Task and TaskParameter classes will be automatically imported with the 'all' import statement. The set of import statements after the 'all' import statements are specific to this example task. The last import statement simply gives us access to the definition of our average function. For this import statement to work as is, the file with the Jython average function needs to be in your CLASSPATH. You can also simply copy the average function into the Jython code of the Task. In that case you don't need the import statement for the 'average' function.

A note about input parameters

As you can see in the above examples, the average function takes one parameter and returns the result. The execute method of the task, on the other hand, has no parameters and returns nothing. The Task defines one input and one output parameter in the constructor, which in Jython is called __init__.

A note about output parameters

One feature of Task is that it tries to minimize its hidden state between calls. This helps if tasks are being executed multiple times: This way, one execution depends as little as possible on the previous executions.

From one execution of the Task to another, most parameters are cleaned (reset to their default values), after invocation:

• The first output parameter will be cleaned after execution of the task. This parameter will be available as the return value of the task and should be stored into a variable for later use: var = task() .
• The second and additional output (or input-output) parameters will be kept in memory until they are accessed, then they will be cleaned: var2 = task.output2 .
• Input parameters are cleaned after execution of the task.

We recommend to use only one output paramater per task, so that no state is kept between task invocations. If you need to return multiple values you can use collections or define an appropiate type that contains all outputs.

Running the Task from Jython

The following commands can be used to run the Average Task from the HIPE Console. We shows three ways of running the task:

from herschel.ia.dataset.all import *
from herschel.ia.numeric.all import *
from Average import Average

x = Double1d.range(5)
columns = 5
data = TableDataset(description = "a test table")
for column in range(columns):
    data["%i" % column] = Column(x)
    x = x + 1

# Create an instance of the Task
avg = Average()

# Print the usage information of the task (the "Signature")
info('avg')

# Set the input parameter 'table'
avg.table = data
calcResult = avg.result
print 'result', calcResult

The Task framework offers different ways to execute the task as well: Calling the execute method using "positional parameters" and "named parameters". Suppose that a task expects three input parameters: One image parameter called 'img', one float indicating a rotation angle 'angle', and one boolean (true or false) called 'takeNeg' indicating whether the negative of the image shall be products.

If you call the execute methods using positional parameters, then the simple order of the parameters tells the Task which is the image, which is the angle and which is the boolean. If you use named parameters, then you are allowed to use any order for the parameters, but every parameters must preceded by its name. The following example illustrates this using our Average Task:

# Invocation using positional parameter
avg(data)

# Invocation using named parameter
avg(table = data)

How To Write a Java Task

This section describes how to turn a Java algorithm into a task. We assume here that you have read the preceding section about writing a Task in Jython.

Again we use a function that calculates an average. This function is called average and is defined in the Java class Function. This is the full Function class:

import herschel.ia.dataset.TableDataset;
import herschel.ia.dataset.Column;
import herschel.ia.numeric.Double1D;

public class Function {

   public static Double1D average(TableDataset table) {
      if (table == null) {
         throw (new NullPointerException("missing table value"));
      }

      int columns = table.getColumnCount();
      double divider = 1.0 / ((double) columns);
      Double1D result = new Double1D(table.getRowCount());
      for (int column = 0; column  < columns; column++) {
         result.mAdd((Double1D) table.getColumn(column).getData());
      }

      return result.mMultiply(divider);
  }

}

The following Java class can be used to test the above code:

import herschel.ia.dataset.TableDataset;
import herschel.ia.dataset.Column;
import herschel.ia.numeric.Double1D;
import java.text.DecimalFormat;

public class TestFunction {

   public static void main(String[] arguments) {
       Double1D result = Function.average(generator());
       show(result);
   }

   /**
    * Generate some test data.
    */ 
   public static TableDataset generator() {
       TableDataset result = new TableDataset("A test table");
       int columns = 5;
       int rows = 5;
       Double1D x = Double1D.range(rows);
       for (int column = 0;column < columns;column++) {
          result.addColumn(("" + column), new Column(x.copy()));
          x.mAdd(1);
       }
       return result;
   }

   public static void show(Double1D data) {
      DecimalFormat twoDigits = new DecimalFormat("0.0");
      int size = data.length();
      System.out.print("result [");
      for (int row = 0;row < size;row++) {
         System.out.print(twoDigits.format(data.get(row)));
         if (row < (size - 1)) {
            System.out.print(",");
         } else {
            System.out.print("] ");
         }
      }
      System.out.println();
  }

}

The result of running TestFunction is:

result [2.0,3.0,4.0,5.0,6.0]              

Task Average

To turn the average algorithim in the Function class into a Task, we will, as before for the Jython function, create a Task that calls the right function. The following is an example of how this can be done:

// Import Task class definitions
import herschel.ia.task.Task;
import herschel.ia.task.TaskParameter;
// Import data types
import herschel.ia.dataset.TableDataset;
import herschel.ia.numeric.Double1D;

public class Average extends Task {

  public Average() {
     super("Averaging of table data set");
     // Add one input parameter: the TableDataset
     TaskParameter parameter = new TaskParameter("table", TableDataset.class);
     parameter.setMandatory(true);
     addTaskParameter(parameter);

     // And declare the output parameter
     parameter = new TaskParameter("result", Double1D.class);
     parameter.setType(TaskParameter.OUT);
     addTaskParameter(parameter);
  }

  public void execute() {
     try {
        setValue("result", Function.average((TableDataset) getValue("table")));
     } catch (Exception e) {
        e.printStackTrace();
     }
  }
}

The following code can be used to test the above Java Task:

import herschel.ia.dataset.TableDataset;
import herschel.ia.numeric.Double1D;
import java.text.DecimalFormat;

public class TestTask {

  public static void main(String[] arguments) {
     Average task = new Average();
     TableDataset data = generate()
     task.setValue("table", data);
     task.execute();
     Double1D result = (Double1D) task.getValue("result");
     show(result);
  }

  public static TableDataset generate() {
     TableDataset result = new TableDataset("A test table");
     int columns = 5;
     int rows = 5;
     Double1D x = Double1D.range(rows);
     for (int column = 0;column < columns;column++) {
        result.addColumn(("" + column), new Column(x.copy()));
        x.mAdd(1);
     }
     return result;
  }

  public static void show(Double1D data) {
     DecimalFormat twoDigits = new DecimalFormat("0.0");
     int size = data.length();
     System.out.print("result [");
     for (int row = 0;row < size;row++) {
        System.out.print(twoDigits.format(data.get(row)));
        if (row < (size - 1)) {
           System.out.print(",");
        } else {
           System.out.print("]");
        }
     }
     System.out.println();
  }
}

Calling a Java task from a Jython script

The script below shows the only difference between calling a task coded in Java (e.g. Average.java) and a task coded in Jython (e.g. Average.py). The import of Average statement ( import JavaAverage ) is different in that we do not need to specify a module name. Note also that the name of the class is changed to JavaAverage in order to avoid a clash of names with our Jython Average class. The test function is identical (albeit shortened).

from herschel.ia.numeric.all import *
from herschel.ia.dataset.all import *
# Import our java task
import JavaAverage

def test():
    x = Double1d.range(5)
    columns = 5
    table = TableDataset(description = "a test table")
    for column in range(0,columns):
        table["%i" % column] = Column(x)
        x = x + 1
    avg = JavaAverage()
    # Invocation using positional parameter
    print 'result', avg(table = table)

Executing the above code in HIPE will define the test() method. Type test() on the HIPE Console to execute it.

Examples

Here we provide some examples on how to use a preprocessor, to perform some actions on your data before starting, and how to write your task if your input consists of arrays. The examples are given in Jython, but can be applied to Java Tasks as well.

Example: Using a preprocessor: Preamble

The preamble allows us to do some preprocessing on our data. For example, our average function calculate the averages of the columns of a table. But what if we wanted our task to calculate the average of two one-dimensional arrays of numbers? We can write a Task to takes two of these vectors as input and use the preamble to create a table, that has these two vectors as columns.

The below example illustrates this. Note that we first invoke the preamble from our parent task (JTask) to guarantee that our needed parameters have a value before putting them into the table.

class AverageArray(JTask):
    # Creation method
    def __init__(self,name = "averageArray"):
        p = TaskParameter("vector1",valueType = PyList, mandatory = 1)
        self.addTaskParameter(p)
        p = TaskParameter("vector2",valueType = PyList, mandatory = 1)
        self.addTaskParameter(p)
        p = TaskParameter("result",valueType = Double1d, type = OUT)
        self.addTaskParameter(p)
        # Create an internal variable table which is our TableDataset
        self.__dict__['table'] = TableDataset()
        
    def preamble(self):
        # In the preamble we do the store the two vectors in  the table
        JTask.preamble(self)
        self.table["0"] = Column(Double1d(self.vector1))
        self.table["1"] = Column(Double1d(self.vector2))
        
    def execute(self):
        self.result = average(self.table)

Note that the execute method is identical to the original Task. The following can be used to try this Task:

sample1 = [1.0, 2.0, 3.0, 4.0]
sample2 = [3.0, 4.0, 5.0, 6.0]
avg = AdaptAverage()

# Invocation using positional parameter
avg(sample1,sample2)
print avg.result

Example: Handling arrays as input

Task Transformer illustrates the use of a task that handles arrays. This example transforms arrays into TableDatasets.

from herschel.ia.task.all import *
from herschel.ia.numeric.all import *
from herschel.ia.dataset.all import *
from java.lang import Integer

class Transformer(JTask):

    def __init__(self, name = 'Vector Transformer'):
       p = TaskParameter(name = 'input', valueType = array(Integer), mandat\
ory = 1)
       self.addTaskParameter(p)
       p = TaskParameter( name = "result", valueType = TableDataset, type = OUT)
       self.addTaskParameter(p)

    def execute(self):
       self.result = TableDataset(description = 'Integrated vector as colum\
n zero')
       r = Double1d(len(self.input))
       index = 0
       for data in (self.input):
           r[index] = data
           index = index + 1
       self.result['0'] = Column(r)

The following can be used to try this Task:

# Test data
sample = [10, 20, 30, 40]
# Create the Task:
transform = Transformer()
# Execute the Task:
transform(sample)
# Get the output:
table = transform.result
# Print:
print table
print table['0']

Including Tasks in HIPE

Tasks should be included in HIPE such that they can be accessed directly from its user interface, in particular the Tasks View.

In short, including a task in HIPE comprises:

• Adding the task to HIPE registry. It is also possible to specify a specific category for your task, such that the task will be available for a specific type of variable.
• Optionally setting validation requirements for a specific parameter, using a ParameterValidator. See Prime input validation.
• Optionally provide a custom task dialog. HIPE automatically provides a default Task dialog panel for the registered tasks.

Please refer to the detailed instructions for a full explanation.

Guidelines for Writing Tasks

This section provides some general guidelines, that are expected to be useful also for simple tasks.

Exceptions

If an error occurs during execution of the task, and the task cannot recover from it, an exception should be raised. This exception must derived from RuntimeException. The JTask API does not declare any exception, so we can't use checked exceptions. If you must raise a checked exception, use the initCause() method of the RuntimeException.

Interrupting Task execution

The Stop button in the HIPE user interface generates an interruption event and sends it to the separate thread where Jython code is running.

This signal is read between consecutive commands of the Jython script. For example, pressing the Stop button interrupts immediately this infinite loop:

while 1:
   print 1

However, this may not be so when the interpreter releases control to a time-consuming Task. If the Task does not periodically check for the interruption signal, pressing the Stop button will have no effect.

You can check for the interruption signal within your code by using the checkInterrupted method of the Task class. If an interruption request is detected, the method will throw an InterruptedException that would be caught by the interpreter, thus cancelling the task. You may pass a String representing the message to issue when the Task is interrupted:

myTask.checkInterrupted(); # Uses default message
myTask.checkInterrupted("Interruption signal received");

Your code should check for the interruption signal with sufficient frequency to allow a timely interruption. For example:

// Within the execute method of your task
for (int i = 0; i < nSteps; i++) {
    Task.checkInterrupted(getName() + " interrupted in step " + i);
    doStep(i);
}

Cleaning Task output

If you use tasks from Jython code, when you access the outputs they are cleaned up automatically. On the other hand, when you call a task from Java code, you need to clean the outputs manually like this:

t.perform();
t. ... // get t results
t.reset();

Of course, if t is going to be garbage collected there is no need to clean it up. Note that the task instances already available in HIPE are not going to be garbage collected.

Tasks and tools Involving Products and Datasets

For tasks that deal with products and datasets, the users (astronomers and calibration scientists) should not be required to perform type conversions between products and datasets. If such conversions are required, they should be dealt with by the software. This in part stems from the fact that manipulation of datasets loses any associated history. It is recommended that all tasks (and tools) should work with, and save outputs as, products.

Stateless and stateful functions

The function, as designed above, is what is called (with respect to its mode of operation) a state-full function . There are two types of functions that exist in the Herschel IA software:

1. Stateless function : this function is called with a set of actual parameters, perform some computation and deliver a result based solely on the current inputs.
2. Stateful function : this function performs some computation based on a set of actual parameters and on its previous internal state . In other words a stateful function is a function with a memory (or a history).

On the command line interactive analysis, data is usually static and therefore the functions used to manipulate them can be either stateful or stateless. To clarify the difference we take a simple averaging of vectors.

The static version of averaging two vectors is simply (call model):

result = average(vector1, vector2)

This method would work well so long as vector1 and vector2 are not themselves the results of averaging (implicitly the state is the weight for the vectors and is equal to 1). In a process where the average is a running average, we could turn this function into a dynamic function by introducing the weights of both input vectors as follows:

result = average(avg1, weight1, avg2, weight2)

This new function can be used in both a dynamic and in a static way. The static call used for instance within the IA (under Jconsole ) could be:

result = average(avg1, 1, avg2, 1)

In the more dynamic QLA environment where the second vector is the data read from a stream, the function would be called as:

runavg = average(runavg, nvectors, vector, 1)
nvectors = nvectors + 1

To sum this up, a stateless function can be used both in static and dynamic environment. It is advantageous, when possible, to write stateless functions.

How to use GUIs with your tasks

Tasks can have an extended set of parameters and/or include results which need to be visualized (a plot or an image). An additional API is provided, which allows the user to interact with the task using a GUI. The GUI and its components are set up such that it can be re-used within other tasks.

To include objects which represents a certain view which is related to the task (most often this is a javax.swing.JComponent), the TaskSignature contains a dedicated parameter called "views". This parameter contains a map object: Map[String, Object]. In this way the developer is capable to include any type of view. Below we show a Java as well as a Jython examples demonstrating the creation and use of view components.

Notes that a task is a DP component, which should be usable in the entire DP environment. This includes the operational pipelines, where no display is available and no GUI should be initialized. The examples below show how to make sure that the GUI is only created when needed.

Java example

import herschel.ia.task.Task;
import herschel.ia.task.TaskParameter;

import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.util.Map;

import javax.swing.JButton;
import javax.swing.JComponent;
import javax.swing.JFrame;
import javax.swing.JPanel;


public class MyAccessTask extends Task implements PropertyChangeListener, ActionListener {
    private JComponent _myTaskDialog;

    public MyAccessTask(){
   super("MyTask");
   makeSignature();
   // instantiate a JComponent including (1) a StringField
   // for the "db" parameter and (2) an "accept" button
   _myTaskDialog = MyTaskDialog(this, getValue("db"));
    } 

    private void makeSignature() {     
   TaskParameter param = new TaskParameter("db");
   param.setValueType(String.class);
   param.setMandatory(false);
   addTaskParameter(param);
   getParameter("db").addPropertyChangeListener(this);

   // create boolean for the dialog component
   // via this parameter the user is able to launch it
   param = new TaskParameter("gui");
   param.setValueType(Boolean.class);
   param.setDefaultValue(Boolean.FALSE);
   param.setType(TaskParameter.IN);
   addTaskParameter(param);
   getParameter("gui").addPropertyChangeListener(this);

   // add view component to the "views" parameter:
   ((Map<Object, Object>) getValue("views")).put("dialog",  _myTaskDialog);
    }


    public void propertyChange(PropertyChangeEvent event) {

       if (event.getPropertyName().equals("dialog")) {
           if ((Boolean) getValue("dialog") && getViews().get("GUI") == null) {
              JPanel jpan = new JPanel();
              jpan.add((JPanel) getViews().get("dialog"));
              JFrame jframe = new JFrame("MyAccessTask Dialog");
              jframe.add(jpan);
                 getViews().put("GUI", jframe);
          }
          ((JFrame) getViews().get("GUI")).setVisible((Boolean) getValue("dialog"));
       }
    }

    public void execute() {
       if ((Boolean) getValue("dialog")) {
           while ((Boolean) getValue("dialog")) {
              try {
                  Thread.sleep(1000);
              } catch (InterruptedException e) {
                  e.printStackTrace();
                 }
           }
       }

       // execute algorithm
    }

    public void actionPerformed(ActionEvent e){ 
       if ( ((JButton) e.getSource()).getText().equals("accept") ) {
           setValue("db", _myTaskDialog.getDbValue());
           setValue("dialog", Boolean.FALSE) ;
      }
    }
}

Jython example

class MyTask(JTask, java.awt.event.ActionListener, java.beans.PropertyChangeListener):

    def __init__(self, name='MyTask'):
       JTask.__init__(self, name)
       self.addTaskParameter(TaskParameter(valueType = \
           array(TmSourcePacket), name="hk", mandatory = 1))
       self.addTaskParameter(TaskParameter(valueType=Boolean, name = \
           "gui", defaultValue=Boolean(Boolean.FALSE)))
       self.addTaskParameter(TaskParameter(valueType = \
           TableDataset, name="result",type=TaskParameter.OUT))
       self.views["jcombo"] = JComboBox()
       self.views["pass"] = JButton("pass plot to task result")    
       self.views["plot"] = PlotXY()
    #
    def propertyChange(self, event):
        if (String('gui').equals(event.getPropertyName())):
            if (self.gui == 1):
                if (self.views.containsKey("GUI") == Boolean.FALSE):                    
                    self.views['frame'] = \
                        JFrame('Binary Structure Task - Display HK Parameters')
                    self.frame.getContentPane().add(self.views['jcombo'])
                    self.frame.getContentPane().add(self.views['plot'])
                    self.frame.getContentPane().add(self.views['pass'])
                    self.views['GUI'] = self.frame
                self.frame.visible = 1

    #

    def actionPerformed(self, event):
        if isinstance(event.getSource(), JComboBox):
          // update plot jcomponent 
        elif isinstance(event.getSource(), JButton):
           // self.result = .........

Re-use of view components outside the task

To support the re-use of tasks as well as the related views, I give the following example: We have a AccessHk task as well as a DisplayParam task which we want to combine in a BrowseHk task, where we re-use the view from the AccessHk task to setup the query, and the view from the DisplayParam which allows to plot select a parameter. The BrowseHk will therefor only contain the glue to combine those views into a higher level task. We define the BrowseHk as a task in order to adopt to the task API, to

• Allow the user to pass: a) an "obsid" as default entry for the task's view, and b) allow the user to retrieve back data into its jide session as one is used to within the task concept
• To support the developer in providing easy syntax to handle data via task parameters.

class BrowseHk(JTask, PropertyChangeListener):
        def __init__(self, name = 'browser'):
                JTask.__init__(self, name, developerAccessMode = 1)
                self.__dict__['apk'] = AccessHk()
                self.__dict__['dpk'] = DisplayParam()
                self.apk.getParameter('result').addPropertyChangeListener(self)
                self.dpk.getParameter('result').addPropertyChangeListener(self)
                self.addTaskParameter(TaskParameter('query',valueType = \
                    array(TmSourcePacket), type = TaskParameter.OUT))
                self.addTaskParameter(TaskParameter('selected',valueType = \
                    TableDataset, type = TaskParameter.OUT))
                self.addTaskParameter(TaskParameter('gui',valueType = \
                    Boolean, defaultValue = Boolean(Boolean.FALSE)))
                self.getParameter('gui').addPropertyChangeListener(self)

                panel = JPanel()
                panel.add(self.apk.views['apk-panel']
                panel.add(self.dpk.views['dpk-panel']
                self.views['main-panel'] = panel

        def propertyChange(self, event):
                if ( String("result").equals(event.getPropertyName()) ):
                        if ( String(event.getSource().getBaseType().getName()).equals
                            ("herschel.ccm.api.TmSourcePacket") ):
                                // event comes from AccessHk
                                ar = event.getNewValue()
                                self.dpk.hkarray = ar
                                self.query = ar
                        else:
                                // event comes from DisplayParam
                                self.selected = self.dpk.result
                elif ( String('gui').equals(event.getPropertyName()) ):
                        if (self.getValue("gui")):
                                if (self.views["Gui"] == None):
                                        frame = JFrame('House Keeping Packet Browser v1.0')
                                        frame.getContentPane().add(self.views['panel'])
                                        frame.setSize(625,680)
                                        self.views['Gui'] = frame
                                self.views['Gui'].visible = 1
                        else:
                                if (self.views["Gui"] != None):
                                        self.views['Gui'].visible = 0
        #
        def execute(self):
                if (self.gui == Boolean.FALSE):
                        self.gui = Boolean.TRUE

Furthermore the developer is able to extract the set of views from a task into its IA session, simply by:

HIPE> views = task.views

Conventions for task GUI labels

The conventions for Task parameter labels in Task dialogs are:

• The primary input parameter should be the first one. Its label will be bold.
• All mandatory parameters (including primary input) will have an asterisk mark in their label. Of course, this does not change the parameter name.
• The other parameters have plain labels.

Label tooltips should be formatted as follows:

  
(optional | mandatory)  type
------------------------------- 
parameter description

The utility JTaskSignatureComponent#getDecoratedLabel(...) can be used to create a label that follows these conventions (including the tooltips).

Example:

Advanced Features

We describe here some features that may not of interest to simple tasks.

User level feedback

Suppose a task can not create the expected outputs because it found an error in the input data. This can not be considered a program failure and has more to do with the notifications an interactive system should give to its operators/final users. Even if the task terminates normally, it should be desirable to provide a way to know if a task was already executed or it is still pending or was interrupted during the execution. Another common situation is that where a time consumer task needs to give some feedback to the user during it execution.

For these situations, all tasks include the following fields in the Signature class: Status, StatusMessage and the Progress.

The Status parameter stores a numeric code without restrictions but with a few, standardized, values:

    Status    Status       Meaning/   
    Value     "Name"       Status Message
    ------    -----------  ---------------------------------------------------------
    100       UNKNOWN      Signature is created but not assigned to a given task yet
    200       READY        Task is ready to be executed
    400       RUNNING      During the execution of the perform method of the task
    000       SUCCESS      Task has finished without problems
    500       INTERRUPTED  Task has been interrupted during its execution
    900       FAILED       Error found during the task execution

Once a task is created the READY value is assigned to it. UNKNOWN value is only used for those cases where a Signature is created before its assignment to a Task or even a pipeline.

Now, when the task perform method is called, its Status is automatically changed to the RUNNING value and it will keep this value until its successful conclusion ( SUCCESS ), an error is found ( FAILED ) or it happens to be interrupted before finish (INTERRUPTED).

This transitions between states are automatically registered into the Status field by the default implementation. The developer can use this information as a quick feedback to the user about the final result of the task. Also, the developer can update the StatusMessage field during the execution of the task as a way to notify the user of current stage into a time consuming task.

The Progress parameter

The Progress field marks the advance in the execution of a given task as a integer value between 0 and 100 . This provide a way to show the user how a single task is performing and how much time is expected this task to last until its conclusion. The developer can update this value at any time during the execution process and the The Task package includes a bean to easily display this value on the screen as the typical progress bar.

The Progress parameter is accessible via the name Signature.PROGRESS and can be used as in the following example.

      public void execute(){
        // assuming to iterate for a number of _iterations
        for (int j=0; j<=_iterations ; j++) {
            // DO SOMETHING DURING THE ITERATION
            //xxxxx
            // LOG PROGRESS INFORMATION
            setValue(Signature.PROGRESS, new Integer(((j*100)/_iterations)));
        // Also, this shortcut is valid for any subclass of Task:
        // setProgress((j*100)/_iterations)
        }
      }

      def execute(self):
        #assuming to iterate for a number of _iterations
        for j in range(_iterations):
            ## DO SOMETHING DURING THE ITERATION
            ##xxxxx
            ## LOG PROGRESS INFORMATION
            self.progress = j*100/_iterations

The FAILED status

The developer must clearly separate the situation where the Task is suppose to return a failed result from any other problem derived from an implementation error or an unexpected situation not well managed by the code. In the latter cases, a RuntimeException shall be raised and the calling method (maybe the graphical environment where the task is running) take care of it.

By definition, a task should be marked as FAILED when, even assuming an error free algorithm and giving the valid inputs, it fails to produce the expected output. A simple example is a task that implements an algorithm to identify the starts into a image. This task should fail when the provided image doesn't contains any start or the algorithm can not distinguish them due to a noisy background.

Optional parameters

Parameters that are facultative must have been given a default value before the task is executed, failure to do so will provoke an exception when parameters values are checked in the preamble. Usually, the default value for a parameter is provided by the task implementer, not the end user. Parameters requiring a value from the user should be tagged as mandatory .