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:
- How to write a simple Java task using Eclipse.
- 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.
- 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
.
- 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.
- This line declares the
TableAverageJavaTask
class. The class, like any task, inherits from Task
.
- 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.
- 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.
- This line defines the description of the
table
parameter. Task parameters, like the task itself, must always have a description.
- This line defines the output parameter, called
average
. It is better to avoid vague parameter names such as result
.
- 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)
- 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.
- 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:
Your comments