Difference: WritingTasks (49 vs. 50)

Revision 502014-02-14 - AlvarGarcia

Line: 1 to 1
 
META TOPICPARENT name="DpHipe"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 70 to 70
 mvln = MyVeryLongNameTask() # New instance
Changed:
<
<
The TaskUtil class offers the isValidName method to check a task name and getDefaultName to generate a default name.
>
>
The TaskUtil class offers the isValidName method to check a task name and getDefaultName to generate a default name.
  Naming style: given a new functionality for a task, there are 2 options: * Role naming: This is how most old task are named, it is object-oriented but is ill suited for functions. (Ex fitsReader, asciiTableReader)
Changed:
<
<
* action-target naming: This is how we recommend to name new tasks as the action comes first and then (optionally) the target. (Ex readFits, readTable, openFile, sortTable, save, restore, pause ...). This is better suited to the functional style that tasks support.
>
>
  • Action-target naming: This is how we recommend to name new tasks as the action comes first and then (optionally) the target. (Ex readFits, readTable, openFile, sortTable, save, restore, pause ...). This is better suited to the functional style that tasks support.
 

Task parameters

Changed:
<
<
Every task has parameters, defined by the TaskParameter class. Task parameters have the following features:
>
>
Every task has parameters, defined by the TaskParameter class. Task parameters have the following features:
 
  • They can be of three kinds: input (IN), output (OUT) or input-output (IO). Use an input-output parameter if your task needs to modify (or replace) the passed object. To set a parameter type:
Line: 121 to 121
 JYTHON: myParameter = TaskParameter("data", valueType = TableDataset, defaultValue=null, ...) JAVA: TaskParameter myParameter = new TaskParameter("data", TableDataset.class);
Changed:
<
<
Note that in Jython you can pass most configuration with the call to create the parameter. In Java, you can use TaskUtil.buildParameter to set most of them in just one step. From a usability POV, the configuration (most members except value) of a task parameter should be constants: a user will not be able to make sense of the system if, under some circumstances, a parameter changes from being mandatory to optional, for example. The way to properly understand this is that we are configuring by code (and data) extended functions definitions.
>
>
Note that in Jython you can pass most configuration with the call to create the parameter. In Java, you can use TaskUtil.buildParameter to set most of them in just one step. From a usability POV, the configuration (most members except value) of a task parameter should be constant: a user will not be able to make sense of the system if, under some circumstances, a parameter changes from being mandatory to optional, for example. The way to properly understand this is that we are configuring by code (and data) extended functions definitions.
  Do not try to reuse reserved words for parameter names (for , if , print ...), otherwise Jython will not be able to understand your task call.
Line: 173 to 173
 
  • The task will not be registered.
  • The task will not even appear in the All folder of the Tasks view.
Changed:
<
<
This means that users can only invoke the task via the command line, either in a script or at the prompt in the Console view. (The root cause is that the Task View (and ToolRegistry) require a primary input).
>
>
This means that users can only invoke the task via the command line, either in a script or at the prompt in the Console view. (The root cause is that the Task View, and ToolRegistry, require a primary input).
  There were two such tasks in the core HIPE software: pause and resume, both in the ia.toolbox.util package, but they are now defined as plain functions.
Line: 185 to 185
  For example, this is a task whose primary input accepts String, Integer and Product:
Changed:
<
<
.public class CombinedTask extends Task {
>
>
public class CombinedTask extends Task {
  private static final String TASKNAME = "combined"; private static final String PRIME = "input"; /** Jython doc string */
Line: 245 to 245
 The framework cleans the data from parameters after executing a task.

Warning, important CHANGES FOR JYTHON CALLS TO TASKS THAT HAVE MULTIPLE OUTPUTS

Changed:
<
<
The way client code retrieves the outputs for tasks than have multiple output is changing. The current way was not Python-like and could bound to generate memory leaks (and even dependencies from previous executions in the case of IO (INOUT) parameters).
>
>
The way client code retrieves the outputs for tasks that have multiple outputs is changing. The current way was not Python-like and could generate memory leaks (and even dependencies from previous executions in the case of IO (INOUT) parameters).
 This will only affect tasks with multiple outputs. When the transition is complete, in the case of multiple outputs, all outputs will be returned as a list (and thus the signature will be cleaned just after execution in all cases). var1, var2 = myTask(). The migration to this new style has been staged as follows:
  • HIPE 11
    • To enable the new syntax you have to add __list__=True to the task call: var1, var2 = myTask(arg=1, ..., __list__=True). If you do not use this form the system will issue a warning every time the task is called. Note that this means that if you just put a variable in the left side of the assignment (var= myTask(arg=1, ..., __list__=True)), var will be a list with all outputs if there is more than one defined (remember that INOUTs are outputs too!).
  • HIPE 12
    • The default syntax will be the new one and you no longer need to add __list__=True. var1, var2 = myTask() will work as is (given that myTask has two outputs defined, of course).
Added:
>
>
  • HIPE 13 or later
    • __list__ is no longer a valid optional parameter in HIPE 13 or later.
 
Changed:
<
<
Note that tasks with multiple outputs will have more restrictions regarding changes in their outputs (order is fixed, adding or removing outputs may result in syntax errors ...). If you want to keep the flexibility to evolve your task it is recommended that you evaluate moving to a task with just one compound output. The best time to do it is now (HIPE 11 development), as users will have to modify their calls, anyway. Also note that it is impossible for the task framework to know how the task has been called wrt the left side of an assignment (the framework just 'sees' the right hand side, i.e. see INFO Task perform: [Full Call] log messages).
>
>
Note that tasks with multiple outputs will have more restrictions regarding changes in their outputs (order is fixed, adding or removing outputs may result in syntax errors ...). If you want to keep the flexibility to evolve your task it is recommended that you evaluate moving to a task with just one compound output. The best time to do it was during HIPE 11 development but it is never too late. Also note that it is impossible for the task framework to know how the task has been called with respect to the left side of an assignment (the framework just 'sees' the right hand side, i.e. see INFO Task perform: [Full Call] log messages).
 
Changed:
<
<
This is why most parameters are cleaned (reset to their default values) after a task is executed in Jython:
>
>
This is why most parameters are cleared (reset to their default values) after a task is executed in Jython:
 
Changed:
<
<
  • The first output parameter is cleaned after execution of the task. You should store the value of this parameter into a variable when you execute the task: var = myTask().
  • IN DEPRECATION: The second and additional output (or input-output) parameters are kept in memory until they are accessed, then they are cleaned: var2 = myTask.output2.
  • Input parameters are cleaned after the task is executed.
>
>
  • The first output parameter is cleared after execution of the task. You should store the value of this parameter into a variable when you execute the task: var = myTask().
  • IN DEPRECATION: The second and additional output (or input-output) parameters are kept in memory until they are accessed, then they are cleared: var2 = myTask.output2.
  • Input parameters are cleared after the task is executed.
 
Changed:
<
<
Try to use a single output parameter per task, so that there are no leftover values after a task execution. If you need to return multiple values you can use collections or define an appropriate type that contains all outputs (check herschel.ia.dataset.Metadata, a general Dictionary-like (map or hash) class).
>
>
Try to use a single output parameter per task, so that there are no leftover values after a task execution. If you need to return multiple values you can use collections or define an appropriate type that contains all outputs (check herschel.ia.dataset.Metadata, a general Dictionary-like class with map and hash implementations).
 
Changed:
<
<
If you execute tasks from Java code, there is no automatic cleanup. You need to clean the outputs manually like this:
>
>
If you execute tasks from Java code, there is no automatic cleanup. You need to reset the outputs manually like this:
 
myTask.perform();
Line: 271 to 273
 myTask.reset();
Changed:
<
<
Of course, if myTask is going to be garbage collected there is no need to clean it up. Note that the task instances already available in HIPE are not going to be garbage collected.
>
>
Of course, if myTask is going to be garbage collected there is no need to clear it up. Note that the task instances already available in HIPE are not going to be garbage collected.
 

Running a task in the HIPE Console view

Changed:
<
<
The Task framework offers different ways to execute the task as well: Calling the execute method using "positional parameters" and "named parameters". Suppose that a task expects three input parameters: One image parameter called 'img', one float indicating a rotation angle 'angle', and one boolean (true or false) called 'takeNeg' indicating whether the negative of the image shall be products.
>
>
The Task framework offers different ways to execute the task as well: Calling the execute method using "positional parameters" and "named parameters". Suppose that a task expects three input parameters: One image parameter called 'img', one float indicating a rotation angle 'angle', and one boolean (true or false) called 'takeNeg' indicating whether the negative of the image shall be produced.
  If you call the execute methods using positional parameters, then the simple order of the parameters tells the Task which is the image, which is the angle and which is the boolean. If you use named parameters, then you are allowed to use any order for the parameters, but every parameter you add after the first named one must be a named parameter too (If you were allowed to put positional parameters after a named one their positions would not be evident).
Line: 288 to 290
 Tasks should be included in HIPE such that they can be accessed directly from its user interface, in particular the Tasks View.

In short, including a task in HIPE comprises:

Changed:
<
<
  • Adding the task to HIPE registry. It is also possible to specify a specific category for your task, such that the task will be available for a specific type of variable.
>
>
  • Adding the task to HIPE registry. It is also possible to specify a specific category for your task, such that the task will be available for a specific type of variable.
 
  • Optionally setting validation requirements for a specific parameter, using a ParameterValidator. See Validating prime input.
Added:
>
>
  • Optionally provide a custom task dialog. HIPE automatically provides a default Task dialog panel for the registered tasks.
 
Changed:
<
<
  • Optionally provide a custom task dialog. HIPE automatically provides a default Task dialog panel for the registered tasks.

Please refer to the detailed instructions for a full explanation.

>
>
Please refer to the detailed instructions for a full explanation.
 

Handling exceptions in tasks

Changed:
<
<
If an error occurs during execution of the task, and the task cannot recover from it, an exception should be raised. This exception should be derived from TaskException (a RuntimeException ). The Task API does not declare any exception (Task.perform), so we can't use checked exceptions. If you must raise a checked exception, use the initCause() method of a TaskException (or subclass thereof).
>
>
If an error occurs during execution of the task, and the task cannot recover from it, an exception should be raised. This exception should be derived from TaskException (a RuntimeException ). The Task API does not declare any exception (Task.perform), so we can't use checked exceptions. If you must raise a checked exception, use the initCause() method of a TaskException (or subclass thereof).
 

Interrupting the execution of a task

Line: 363 to 361
  Now, when the task perform method is called, its Status is automatically changed to the RUNNING value and it will keep this value until its successful conclusion ( SUCCESS ), an error is found ( FAILED ) or it happens to be interrupted before finish (INTERRUPTED).
Changed:
<
<
This transitions between states are automatically registered into the Status field by the default implementation. The developer can use this information as a quick feedback to the user about the final result of the task. Also, the developer can update the StatusMessage field during the execution of the task as a way to notify the user of current stage into a time consuming task.
>
>
These transitions between states are automatically registered into the Status field by the default implementation. The developer can use this information as a quick feedback to the user about the final result of the task. Also, the developer can update the StatusMessage field during the execution of the task as a way to notify the user of current stage into a time consuming task.
 

Showing task execution progress

Changed:
<
<
The Progress field marks the advance in the execution of a given task as a integer value between 0 and 100 . This provide a way to show the user how a single task is performing and how much time is expected this task to last until its conclusion. The developer can update this value at any time during the execution process and the The Task package includes a bean to easily display this value on the screen as the typical progress bar.
>
>
The Progress field marks the advance in the execution of a given task as a integer value between 0 and 100 . This provide a way to show the user how a single task is performing and how much time is expected this task to last until its conclusion. The developer can update this value at any time during the execution process and the Task package includes a bean to easily display this value on the screen as the typical progress bar.
  The Progress parameter is accessible via the name Signature.PROGRESS and can be used as in the following example.
Line: 421 to 419
 

Task compliance checklist

Changed:
<
<
Developing a task that looks native involves quite a few steps. We have provided a list with the qualities a task should hold: ChecklistTask
>
>
Developing a task that looks native involves quite a few steps. We have provided a list with the qualities a task should hold: ChecklistTask (this is a TWiki page only for internal developers).
 
 
This site is powered by the TWiki collaboration platform Powered by Perl