Overview

This tutorial teaches you how to create a simple Java tasks and import it in HIPE.

Audience

Read this tutorial if you have, or want to write, Java classes that you want to turn into tasks.
Unless you have existing Java code, we recommend that you write your tasks in Jython instead. See the Creating your first Jython task tutorial for more details.

Prerequisites

This tutorial assumes that you are familiar with some Java programming concepts, such as Java packages, classes and methods.

Objectives

This tutorial will teach you the following:
  • What a HIPE task is.
  • How to write a simple Java task.
  • How to add the task to HIPE as a plug-in.
  • How to share your plug-in with other users.

Contents


Installing and configuring Eclipse

Although you could work on a task source file with any text editor, installing a development environment will allow you to work more efficiently. We strongly recommend you use the Eclipse development environment. Besides being free and multi-platform, it has the crucial advantage of some Herschel-specific plugins that will make your life much easier.

Note: These instructions have been tested with Eclipse version 3.7 (Indigo). Some steps may differ in other versions.

Follow these steps to install Eclipse and configure it for use with HIPE source files:
  1. Go to http://www.eclipse.org and choose Eclipse IDE for Java Developers from the download page. Download the appropriate package for your platform.
    DownloadEclipse.png
  2. Install Eclipse on your computer.
  3. Start Eclipse and choose Help > Install New Software. The Install window opens.
  4. In the Install window, click Add. The Add Repository dialogue window opens.
  5. Write http://herschel.esac.esa.int/hcss/eclipse/ in the Location field and any name you like in the Name field. Click OK.
  6. Tick the Uncategorized checkbox that has appeared in the Install window, and click Next. Follow the instructions on screen to complete the installation.
Eclipse is now ready for you to develop HIPE software. Next you have to create a project to host your task source code.

Writing the task in Eclipse

  1. Start Eclipse.
  2. Choose File -> New -> Java Project. The New Java Project dialogue window opens.
    NewJavaProject.png
  3. Enter TableAverageJavaTask in the Project name field. Click Next. The Java Settings page opens.
  4. Click on the Libraries tab, and then on Add Library The Add Library dialogue window appears.
    AddLibrary.png
  5. Select HCSS Project Container from the list and click Next.
  6. 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 (12.0 for HIPE 12.x, and so on), and click Fetch latest to get the latest build.
    HcssProjectContainer.png
    These settings work for the simple example in this tutorial. If you are developing instrument-specific software, set the Project field to hcss.dp.hifi, hcss.dp.pacs or hcss.dp.spire.
  7. Click Finish, then Finish again in the New Java Project dialogue window.
  8. Right click on the project name in the Package view, and choose New > Class from the context menu. The New Java Class dialogue window appears.
  9. Write herschel.ia.tableaveragejava in the Package field, and TableAverageJavaTask in the Name field. In the Superclass field, change java.lang.Object to herschel.ia.task.Task.
  10. Click Finish.Eclipse creates the class and opens the source file with this skeleton code:
    package herschel.ia.tableaveragejava;
    import herschel.ia.task.Task;
    public class TableAverageJavaTask extends Task {
    }
Your Eclipse project is now fully configured. You now have to modify the source file as described in the next section.

The source code of the Java task

This is the complete source code of the Java task:
  • 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));
            }
        }
    }
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.
  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.
Once you have modified the source code, you must export the project to a JAR file.

Exporting the task to a JAR file

  1. Right click on the project name in the Package view and choose Export. The Export dialogue window opens.
  2. Click JAR file in the Java folder and click Next. The JAR File Specification page opens.
  3. Write a name for your JAR file in the JAR file field and click Finish. Eclipse generates the JAR file. If a message appears saying that the JAR export finished with warnings, ignore it.
Your task is now packaged in a JAR file. To import this JAR file into HIPE, the easiest way is to wrap it into a HIPE plug-in. Read on to find out how.

Creating a HIPE plug-in

By creating a plug-in, you can have your task automatically available in the Tasks view every time you start HIPE. Creating a plug-in is as easy as creating a zip file.
  1. Create a Jython script called plugin.py. In our case the script would be the following:
    from herschel.ia.tableaveragejava import TableAverageJavaTask
    toolRegistry = TaskToolRegistry.getInstance()
    toolRegistry.register(TableAverageJavaTask(), [Category.GENERAL])
    del(toolRegistry)
This script registers the task so that it is picked up by HIPE. The task is assigned to the GENERAL category. 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.
  1. 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.
    • A 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.
Your plug-in is now ready. Read on to learn how to install it.

Installing the HIPE plug-in

  1. In HIPE, choose Tools > Plug-ins The Plug-ins dialogue window opens.
    PluginsWindow.png
  2. Click Install new. The Install new plug-in dialogue window opens.
    InstallNewPlugin.png
  3. Click the folder icon and navigate to the zip file you have created. Click Open.
  4. Click Install. HIPE should inform you that the plug-in has installed correctly.
  5. Restart HIPE.
The plug-in should now be installed correctly. Go to the Tasks view, open the All folder and type the first letters of the task name to jump to the right place in the list. You should see your new task. The task should also appear in any category you added it to, inside the By Category folder.

Sharing your modified task

You may want to share your task with your colleagues or with a wider user base. You have the following options:
  • To share your task among a small circle of colleagues: You can simply circulate by email the .zip file with the plug-in.
  • To share your task among a wider circle of users: You can post the .zip plug-in file to the HIPE Community wiki. Open a free account, then click Pages and Files in the top left corner of the page to upload your file. Then edit one of the pages, or add a discussion post, with a link to the file you uploaded.
  • To add your task to the official list of Herschel user-contributed software: Open a Helpdesk ticket with your request. For more information read the Herschel Tools Contributor's Guide.
  • To add your plug-in to the official list of HIPE plug-ins: Send an email to Álvar García.