# Package uk.ac.starlink.task

A framework for invoking user-level tasks.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  Environment | Defines an execution environment within which tasks can operate.
  Executable | Defines an object which does the work of a task without any further user or environment interaction.
  MultiParameter | Marker interface which marks a parameter as one which can have multiple appearances on the command line.
  Task | Defines a user-level task.

- Class Summary
  Class | Description
  --- | ---
  BooleanParameter | Parameter value representing a boolean value.
  ChoiceParameter<T> | Parameter whose legal value must be one of a disjunction of given values.
  DoubleParameter | Parameter representing a double precision number.
  InputStreamParameter | Parameter which can provide an input stream based on its value.
  IntegerParameter | Parameter representing an integer value.
  InvokeUtils | Provides some utility functions used by classes which invoke tasks.
  LineEnvironment | Execution environment for use from the command line.
  LineFormatter | Compact log record formatter.
  LineWord | Represents a single word on the command line used as by LineEnvironment.
  LongParameter | Parameter representing a long integer value.
  MultiTaskInvoker | Invokes tasks from a command line when the tasks are available from an `ObjectFactory`.
  ObjectFactoryParameter<T> | Parameter whose (user-supplied) string values correspond to nicknames from an `ObjectFactory`.
  OutputStreamParameter | Parameter for selecting an output stream to write to.
  Parameter<T> | A Parameter describes the function of one of a task's parameters.
  SingleTaskInvoker | Invoker which only knows how to invoke a single given task.
  StringParameter | Parameter for holding string values.
  TerminalEnvironment | Implementation of Environment which accepts an initial command line, and communicates with the user using standard input and standard output.
  TerminalInvoker | Invokes Task objects in a way suitable for use from the `main` method, using a command line interface.
  URLParameter | Parameter representing a URL value.

- Exception Summary
  Exception | Description
  --- | ---
  AbortException | Exception generated when the user signals an intention to abort a task.
  ExecutionException | Exception generated when a task does not complete correctly for some known reason.
  ParameterValueException | Exception generated when the value of a parameter is invalid.
  TaskException | Superclass for exceptions in the task package.
  UsageException | An Exception thrown when a task is invoked with the wrong usage.

## Package uk.ac.starlink.task Description

A framework for invoking user-level tasks.

This package provides the necessary infrastructure for writing tasks that do things for users, along the same lines as ADAM A-tasks. An example of use is given in the separate NDTools package.

At the moment all the necessary machinery is provided for invoking tasks from the command line in a way that looks ADAM-like, but it is designed so that, for instance, a GUI-style invoker could be written to invoke the same tasks.

The provided components are as follows:

`Parameter`
  is an object which knows about the name, default value, data type, validity constraints etc of a parameter of a task. It also stores the actual value of the parameter when it has been obtained from the environment. When it has obtained a value it can return it as a string. `Parameter` can be subclassed to enforce different validity constraints or so it knows how to return itself as some object other than a string (see for instance `IntegerParameter`).
``Environment``
  is an interface which defines how to request the value of a parameter. It can also tell you about what output stream to use for messages to be dispatched to the user.
`TerminalEnvironment`
  is an implementation of `Environment` which assumes a user is sitting at a terminal with standard input and standard output.
`TerminalInvoker`
  given a map of task names to `Task` objects will use a `TerminalEnvironment` to invoke tasks from an `args`-style string array.
``Task``
  is the interface which user tasks themselves have to implement. A Task must be able to return a list of the parameters which it uses; since each parameter knows its name, default value, order on the command line, prompt string etc, this tells the Environment everything it needs to know about how to get the value, including what to prompt the user etc. It must also be able to invoke itself on request. During invocation, it can interrogate its parameters to find out what their values are.

Setting up a user-level package containing tasks is then a case of writing a top-level class with a `main` method which invokes `TerminalInvoker`, and writing a number of classes which implement `Task`. See the NDTools package for an example.

To invoke the same tasks from a GUI you'd want to write something like a `GUIEnvironment` and `GUIInvoker` class.

Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.