Overview

This tutorial teaches you how to take one of the Java tasks included in HIPE and modify it to suit your needs.

Audience

Read this tutorial if you want to change the behaviour of a task included in HIPE. For example, you may want to tweak the algorithm used in a pipeline task. This tutorial explains how to modify a Java task. If you want to modify a Jython task, read the Modifying an existing Jython task tutorial.

Prerequisites

This tutorial assumes that you are familiar with the following:
  • Some Java programming concepts (Java packages, classes, methods).
  • Basic notions about HIPE tasks. If this is not the case, read What is a HIPE task? in the Creating your first Java task tutorial.

Objectives

This tutorial will teach you the following:
  • How to get the source code of an existing HIPE task.
  • How to create a modified version of the task.
  • How to create a plug-in import the modified task into HIPE.
  • How to switch between the original and the modified version.
  • How to share the modified task.

Resources

For this tutorial we will use as example the imageAbs task.

Contents


Obtaining the task source code

To complete these steps you must have the source code of HIPE installed. You must have ticked the Would you like to have the source code installed? checkbox when installing HIPE.
InstallSourceCode.png
  1. Locate the task in the Tasks view of HIPE. You can open the All folder and type the first letters of the task name to find the task more quickly.
  2. Right click on the task name and choose View source. The source code opens in a new tab inside the Editor view.
  3. Choose File -> Save as and save the file to a different location.
You now have a working copy of the task source code. In this tutorial we save the original task source code as a new file called MyImageAbsTask.java.

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.

Creating an Eclipse project

  1. In Eclipse, choose File -> New -> Java Project. The New Java Project dialogue window opens.
    NewJavaProject.png
  2. Write any name you want in the Project name field, for example MyImageAbsTask. Click Finish.
  3. Copy the source file you saved (in our case MyImageAbsTask.java) to the src directory of your Eclipse project. In our case it would be something like workspace/MyImageAbsTask/src/.
  4. Right click on your project in the Package view of Eclipse and choose Refresh, or press F5. Eclipse now shows the file inside the project.
If you have followed the above steps correctly, you will see a little white cross on red background on the icon for the MyImageAbsTask project, and on all the icons down to the file you just added. This is because you still need to configure the project. Read on to find out how.

Configuring your Eclipse project

  1. Right click on the project entry in the Package view and choose Properties. The Properties dialogue window appears.
  2. Click the Java Build Path section and select the Libraries tab.
  3. Click Add Library. The Add Library dialogue window appears.
  4. Select HCSS Project Container from the list and click Next. The HCSS Project Container configuration screen appears.
  5. Configure the options of the HCSS Project Container as follows:
    Project Projects are listed in the Developer Tracks pages of the Continuous Integration system, and have names such as hcss.dp.core. If you are developing for the core system only (no instrument-specific software) write hcss.dp.core. If you are developing for an instrument, write one of hcss.dp.hifi, hcss.dp.pacs and hcss.dp.spire. In this case we are modifying a core system task, so hcss.dp.core is appropriate.
    Track Corresponds to the major version of HIPE you are developing for. Write 8.0, 9.0 or whatever version of HIPE you have installed. You can check by choosing Help > About in HIPE. If you see for example 8.0.375 you have to write 8.0 in this field.
    Build You can choose to download a specific build or click Fetch latest to get the most recent one for the major version you have selected.
    Build Updates Here you can choose how often Eclipse will look for and install updated builds. The default is not to look for updates.
  6. Click Finish and then OK.
Your Eclipse project is now configured for HIPE development. However, the error symbol (white cross on red background) has not yet disappeared. This is because there are still a couple of things to fix in the source file. These are mentioned in the next section, about modifying the task source.

Modifying the source

  1. In the Package view of Eclipse, open the MyImageAbsTask project by clicking the small white arrow to the left of its name. Do the same with the src and (default package) folders. You should now see an entry for the file.
  2. Double click on the MyImageAbsTask.java file. The file opens in the Eclipse editor.
  3. Next to thepackage herschel.ia.toolbox.image;line, you will see an icon representing a lightbulb with a small white cross on red background next to it. Click on that icon. A popup appears, offering two solutions for the problem.
  4. Of the two solutions, double click on the one reading: Move 'MyImageAbsTask.java' to package 'herschel.ia.toolbox.image'. Eclipse moves the class to the correct package and the error disappears.
  5. Go to the line declaring the ImageAbsTask class. This line is marked with another error. Change the class name to MyImageAbsTask. The second error disappears.
  6. Change the public constructor name from ImageAbsTask to MyImageAbsTask. The third error disappears.
  7. Change the line super("imageAbs"); to super("myImageAbs");.
  8. Change the argument of the this.setDescription method to something like "This is a modified version of the imageAbs task". This is to distinguish the modified task from the original one.
  9. Save the file.
You have successfully imported the task into Eclipse and made a small change to its description. Of course, in a real scenario, you would make deeper changes to the source code, but the process remains the same. Now you can export your modified task 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.toolbox.image import MyImageAbsTask
    toolRegistry = TaskToolRegistry.getInstance()
    toolRegistry.register(MyImageAbsTask(), [Category.GENERAL, Category.IMAGE])
    del(toolRegistry)

    This script registers the task so that it is picked up by HIPE. The task is assigned to the GENERAL and IMAGE 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.
  2. Create a zip file containing the plugin.py file and the JAR file previously created by Eclipse, in a jars directory:
    plugin.py
    jars/MyImageAbsTask.jar
The zip file name must be made by three parts:
    • The plug-in name, for example MyImageAbsPlugin.
    • 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 been 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.

Switching between the original and the modified task

Now you have the original and modified task loaded in HIPE. You may have a pipeline script that calls the original task, and you may want it to call the modified task instead. You can of course modify the pipeline script and replace the original task name with the modified task name. However, this can be tedious and error-prone if the script calls the task many times.
To complete this task you must know the fully qualified name of the original task. To find the fully qualified name of a task, right click on the task name in the Tasks view and choose Help in URM. The task entry in the User's Reference Manual opens in your browser. The Full Name entry in the table at the top is the fully qualified name. For the imageAbs task, the qualified name is herschel.ia.toolbox.image.ImageAbsTask.
You can create an alias to use the modified task instead of the original one, as in the following example:
print imageAbs.description
# This task takes the absolute value of the intensities in an image.
imageAbs = myImageAbs  # Creating alias
print imageAbs.description
# This is a modified version of the imageAbs task
After the above steps, the original task is hidden by the modified task. The following example shows how to revert to the previous situation. This is where the fully qualified name of the task comes into play:
del (imageAbs)  # Removing the alias
# Recreating instance of original task
imageAbs = herschel.ia.toolbox.image.ImageAbsTask()
The original task is now available again, while you can still call the modified task by using the myImageAbs name.

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 Alvar GarcĂ­a.