(r13) MyFirstJavaTask < Public

Public Web>DpHipe>MyFirstJavaTask (revision 13) (raw view)~~EditAttach~~
<!--
   * Set TOPICTITLE = My first Java HIPE task
-->

| *PDF Version* | [[%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdforientation=portrait&pdftoclevels=2][Portrait]] | [[%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdforientation=landscape&pdftoclevels=2][Landscape]] |

%ICON{"help"}% *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 <a href="mailto:drizzo@sciops.esa.int?subject=Comment on public Wiki page: %TOPICTITLE%&body=Dear Editorial Board,">send a message</a> to the Editorial Board to tell us about it. Thank you in advance!*

---+ My first Java HIPE task

%STARTINCLUDE%
This tutorial will teach you the following:

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

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 _[[HipeDevGettingStarted][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 [[http://herschel.esac.esa.int/hcss-doc-8.0/index.jsp#um:sec-tabledatasets][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 _[[HipeDevGettingStarted][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:

<verbatim>
package herschel.ia.tableaverage;

import herschel.ia.task.Task;

public class TableAverageTask extends Task {

}
</verbatim>

Complete the source code as follows:

<verbatim>
package herschel.ia.tableaveragejava;  // 1

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

public class TableAverageJavaTask extends Task {  // 3

    public TableAverageJavaTask() {
        super("tableAverageJava");
        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());
        }

            setValue("average", average.multiply(divider));

        }
    }
}
</verbatim>

Let us examine some lines of the script.

   1. This line sets the package as ==herschel.ia.tableaveragejava==. You can set whatever suits your project or organisation. It does not need to be a subpackage of ==herschel.ia==.
   1. 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.
   1. This line declares the ==TableAverageJavaTask== class. The class, like any task, inherits from ==Task==.
   1. 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.
   1. 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.
   1. This line defines the description of the ==table== parameter. Task parameters, like the task itself, must always have a description.
   1. This line defines the output parameter, called ==average==. It is better to avoid vague parameter names such as ==result==.
   1. 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:

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

   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.
   1. 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 (or [[%ATTACHURL%/MyJavaAverage_0.1.zip][download]] the one we made for you) containing the ==plugin.py== file and the JAR file previously created by Eclipse, in a ==jars== directory:

<verbatim>
plugin.py
jars/TableAverageJavaTask.jar
</verbatim>

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 [[MyFirstJythonTask][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 [[MyFirstJythonTask][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 [[WritingTasks][Writing tasks]] page has more details on techniques and best practices to develop HIPE tasks.
   * The [[DpHipeTools][Adding tools to HIPE]] page has more details on adding tasks and other components to HIPE.
   * The [[DpHipePluginsDeveloperManual][Plug-in developer manual]] has more details on developing HIPE plug-ins.

---++ Your comments

%COMMENT%
<span class="commentPlugin commentPluginOutputOneliner">   * wrt Turning the task into a HIPE plug-in:

I'm not sure about plug-ins but the preferred way in init.py's to register tasks is:

toolRegistry.register(TableAverageJavaTask(), [Category.GENERAL, Category.SPECTRUM])

Do not create a variable, just create the instance in the call to the registry.
 -- Main.JavierDiaz - 29 Nov 2011 - 09:33</span></span><!--/commentPlugin-->

<!--
   * Set ALLOWTOPICCHANGE = Main.RegisteredUsersGroup, Main.TWikiAdminGroup
-->
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
zip	MyJavaAverage_0.1.zip	r1	manage	2.6 K	2011-10-14 - 09:43	DavideRizzo	Sample Java HIPE plugin
Topic revision: r13 - 2011-11-29 - JavierDiaz
Public
Webs
Public
TWiki