There are three types of objects: Plain-Old-Elements (POEs), Collections and Maps, and Tasks.

POEs

There is no interface to implement here, though usually such elements will be ncsa.tools.common.UserFacing. The only constraints on such elements are as follows:

POE Attributes

These are directly settable from the org.dom4j.Attribute value string if they are primitiveAssignable.

  • A primitiveAssignable object is one which has a java.lang.String constructor; in Ogrescript, the supported primitiveAssignables are: primitive wrappers, java.lang.String, java.io.File or java.net.URI objects. For the sake of concision, we also include the actual primitive types under this term, though technically they are not objects.

Attributes are also settable through a value dereferenced from the environment.

For each settable attribute, the object must have a method with the following form:

  • string-value setters:
    • setAttributeName( exactType );
  • dereferenced-value setters:
    • setAttributeName( assignableType ).

That is, dereferenced value parameter types can be polymorphic.

POE Child Elements

These can be POEs, java.util.Collections or java.util.Maps. For each such element, the parent type must have a setter or adder method which handles it. Unlike attributes, elements imply that the corresponding object must be instantiated when its parent is. Because introspection is used to do this, the parameter type must correspond to the exact class of the object (it cannot be an interface or superclass).

  • element setters:
    • setElementTag( exactType );
  • element adders (if these are being accumulated into a list-like structure):
    • addElementTag( exactType ).

All POEs should be declared as extensions to the ncsa.tools.common.elementType extension point. For more remarks on element tags, see 2. XML Tag Name Constraints.

Collections and Maps

Most java.util data classes are supported. See again tag-name constraints.

Tasks

These should implement the ncsa.tools.ogrescript.ITask interface. They must be declared as extensions to the ncsa.tools.ogrescript.ogreTask extension point. Tasks are special cases of a simple element and must meet those requirements as well; they are the objects which do the actual work.

There are three convenience abstract base classes available for extension:

  1. ncsa.tools.ogrescript.tasks.OgreScriptBaseTask: use this when your task has no return values.
  2. ncsa.tools.ogrescript.tasks.OgreScriptTask: use this when your task makes return values available.
  3. ncsa.tools.ogrescript.tasks.OgreScriptTaskContainer: a "self-configuring" (see below) base class for tasks whose job is to execute other tasks.

ncsa.tools.ogrescript.ISelfConfiguring

This interface denotes a special object which acts as a kind of container. Wrapper configuration halts at an element of this type, leaving it to manage the configuration of its own attributes and children.

Such a container may have, but does not require, specific setters or adders for its children (it contains a reference to its own wrapped xml); however, there is a constraint on the tags of elements whose direct parents are self-configuring. See again 2. XML Tag Name Constraints.

The self-configuring abstraction is necessary in the case where a task or element executes a series of subtasks, and the side-effects from a given subtask should determine the configuration of a subsequent subtask. It is also convenient in the case of generic handlers, such as the Assign and Declare tasks, where the input (the elements and attributes) to the task are general or open-ended.

  • No labels