Did you spot something wrong or missing on this page? If you have an account on this TWiki, you can fix it yourself by editing the page. If you don't have an account, you can send a message to the Editorial Board to tell us about it. Thank you in advance!

My first Java HIPE task

This tutorial will teach you the following:

1. How to write a simple Java task using Eclipse.
2. How to add the task to HIPE as a plug-in.

Requisites:

• You know at least the basics of Java and are familiar with concepts such as package, class and superclass.
• You have set up Eclipse for HIPE development. To learn how to do so, read the Getting started with HIPE development tutorial to the end of the Creating an Eclipse project section.

Writing the task in Eclipse

This tutorial has been tested with Eclipse 3.7 "Indigo". Steps may differ for other versions of Eclipse.

The following is a simple Java task that takes a table dataset as input and outputs an array with the averages of each row of the table dataset. For more information about table datasets, see the Scripting and Data Mining guide.

Start Eclipse. Choose File --> New --> Java Project. Enter TableAverageTask in the Project name field. Click Next.

In the next window, click on the Libraries tab. Click Add Library. The Add Library dialogue window appears. Select HCSS Project Container from the list and click Next. If you do not see HCSS Project Container among the available libraries, you need to install the HCSS Project plugin as described in the Getting started with HIPE development tutorial.

In the configuration dialogue window for the HCSS Project Container library, enter hcss.dp.core in the Project field, the major version number of your HIPE installation in the Track field (8.0 for HIPE 8.x, and so on), and click Fetch latest to get the latest build. These settings work for the simple example in this tutorial; if you are developing instrument-specific software, set the Project field as hcss.dp.hifi, hcss.dp.pacs or hcss.dp.spire.

Click Finish, then Finish again in the New Java Project dialogue window.

Right click on the project name in the Package Explorer view, and choose New --> Class from the context menu. The New Java Class dialogue window appears. Write herschel.ia.tableaverage in the Package field, and TableAverageTask in the Name field. In the Superclass field, change java.lang.Object to herschel.ia.task.Task.

Click Finish. Eclipse creates the class and opens the source file with the skeleton code:

package herschel.ia.tableaverage;

import herschel.ia.task.Task;

public class TableAverageTask extends Task {

}

Complete the source code as follows:

package herschel.ia.tableaverage;  // 1

import herschel.ia.task.Task;  // 2
import herschel.ia.task.TaskParameter;
import herschel.ia.dataset.TableDataset;
import herschel.ia.numeric.Double1d;

public class TableAverageTask extends Task {  // 3

    public TableAverageTask() {
        super("tableAverage");
        setDescription("Computes the average of each row of a table dataset");  // 4
        TaskParameter parameter = new TaskParameter("table", TableDataset.class);  // 5
        parameter.setType(TaskParameter.IN);
        parameter.setMandatory(true);
        parameter.setDescription("The table of whose rows to compute the average"); //6
        addTaskParameter(parameter);

        parameter = new TaskParameter("average", Double1d.class);  // 7
        parameter.setType(TaskParameter.OUT);
        parameter.setDescription("The array of averages of the table's rows");
        addTaskParameter(parameter);
    }

    public void execute() {  // 8
        TableDataset table = (TableDataset) getParameter("table").getValue();
        if (table == null) {
            throw (new NullPointerException("Missing table value"));
        }

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

        try {
            setValue("average", average.multiply(divider));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Let us examine some lines of the script.

1. This line sets the package as herschel.ia.tableaverage. You can set whatever suits your project or organisation. It does not need to be a subpackage of herschel.ia.
2. This line and the following import the needed classes: Task and TaskParameter are needed for any task, while TableDataset and Double1d are needed for the specific computations done in this task.
3. This line declares the TableAverageJavaTask class. The class, like any task, inherits from Task.
4. This line sets the description of the task. It is what you see in the tooltip that appears when you hover on the task name in the Tasks view of HIPE. Every task must have a description.
5. This line defines a task parameter. This parameter is called table and is of type TableDataset. The next two lines state that table is an input parameter and is mandatory.
6. This line defines the description of the table parameter. Task parameters, like the task itself, must always have a description.
7. This line defines the output parameter, called average. It is better to avoid vague parameter names such as result.
8. This line defines the execute method. This is the heart of any task: it is the function that does the actual data processing.

Save the file. Right click on the project name, and choose Export from the context menu. Choose JAR File from the list and click Next. Write a name of your liking in the JAR file field (for example, TableAverageJavaTask.jar) and click Finish. Eclipse creates the JAR file.

Turning the task into a HIPE plug-in

Create a Jython file named plugin.py. Write the following in the file:

from herschel.ia.tableaverage import TableAverageJavaTask
tableAverageJava = TableAverageJavaTask()  # 1
toolRegistry = TaskToolRegistry.getInstance()
toolRegistry.register(tableAverageJava, [Category.GENERAL, Category.SPECTRUM])  # 2
del(toolRegistry)

1. This line creates an instance of the task. Note that from the task name TableAverageJavaTask we obtained tableAverageJava as instance name. This is a general rule. The task name is made of words with capitalised initials and ends with Task. The instance name starts with a lower case letter and drops the Task part.
2. The task is assigned to the GENERAL and SPECTRUM categories. This is not required, since the task would appear anyway in the All folder of the Tasks view in HIPE. The available categories are GENERAL, CUBE, IMAGE, SPECTRUM, HIFI, PACS and SPIRE.

Now create a zip file containing the plugin.py file and the JAR file previously created by Eclipse, in a jars directory:

plugin.py
jars/TableAverageJavaTask.jar

The zip file name must be made by three parts:

• • The plug-in name, for example TableAverageJavaPlugin.
  • An underscore character.
  • The plug-in version number, which can be any combination of digits separated by dots. For example, 0.1, 1.0.0, 2.3.3 and so on.

The plug-in is now ready.

Installing, running and sharing the plug-in is done in the same way as described in the My first Jython task tutorial. The only difference is that we called the Java task class TableAverageJavaTask instead of TableAverageTask. Correspondingly, the task instance is tableAverageJava instead of tableAverage. This allows you to install the plug-ins from this tutorial and from the My first Jython task tutorial without name clashes.

Where to go from here

You are now ready to develop more complex tasks and plug-ins. You may find the following resources useful:

• The Writing tasks page has more details on techniques and best practices to develop HIPE tasks.
• The Adding tools to HIPE page has more details on adding tasks and other components to HIPE.
• The Plug-in developer manual has more details on developing HIPE plug-ins.

Your comments