Unit Annotations Reference - Hyper/J Universe Construction Toolkit

Unit Annotations for Hyper/J Composition: Syntax and Gather Markers; Interaction Elements; Concern Element; Java Unit Form Attribute Values; Interaction Mode Attribute Values; Dimensional Mode Element Values

Unit annotations are stylized Java comments that can be easily accessed by the gather application. Each unit annotation defines an XML element that describes the associated software unit. Two kinds of XML elements are captured by unit annotations. Interaction elements, such as <declare>, <extend>, and <use>, define the permissible interactions among composable units. The <concern> element specifies additional dimensions of concern for each unit.

These annotations are largely experimental. For robust program composition, these elements will need flexible namespace management mechanisms. XML namespaces provide a powerful mechanism, and may be sufficient for integrating independently developed subsystems.

Warning: these XML element defintiions are subject to change!!

Syntax and Gather Characters

Unit annotations take the form of a Java comment with a distinctive XML-like prefix ("//<"). The gather application collects each line and reformats it as a standard XML element. Additional options allow the gather application to collect the Java definitions of each software unit.

Following the unit annotation prefix is a gather marker that defines the lexical handling for each annotation. The gather marker defines whether a unit definition is included as the text content of the element. The gather marker also indicates if the annotation has any nested annoations. Typically, class units have nested annotations for public fields and methods. Successful use of the gather markers requires that each Java unit is defined on a single line. Forturnately, this assumption follows widely accepted practice in Java development.

Gather Marker	Description	Source	Element Form
`"-"`	Include only the current line, which should terminate the XML element. Typically used with non-content XML elements, such as the `<concern ... />` element.	no	empty tag
`"="`	Include the current line and any nested Unit Annotations. Include the unit definition as the text content for this element. After the source line is copied to the output, the element is closed. Typically used for Java field and method declarations.	unit definition	start tag with automatic end tag
`"+"`	Include the current line and any nested Unit Annotations. Include the unit definition as the text content for this element. After the source line is copied to the output, the element remains open. Typically used for Java class declarations.	unit definition	start tag only
`"/"`	Generate an end tag for a previous element. Typically used for Java class declarations.	no	end tag only

Interaction Elements

The three basic interaction elements - <declare>, <extend>, and <use> - define the anticipated role each annotated unit. During composition, a named interface should not be extended or used unless there is exactly one declaration. Future validation tools will confirm that each interface is extended or used only by compatible units.

Other interaction elements describe combination roles. For example, the <define> element indicates an interface that is both <declare>d and <extend>ed. The -use variations indicate that another unit in the current module also calls (i.e. "relies-on") the annotated unit.

Interaction elements include a name and form attributes to define the symbolic name and form of each software unit. The mode attribute is only used with the <declare>, <define>, and <extend> elements (including their -use variations).

Element Name	Intent	Declare	Extend	Use
`declare`	Declare an interface.	Yes
`extend`	Provide an implementation for an interface.		Yes
`define`	Declare an interface, and provide a base-line implementation.	Yes	Yes
`use`	Call an interface or `get()` a variable value.			Yes
`define-use`	Declare, implement, and call an interface.	Yes	Yes	Yes
`extend-use`	Implement and call an interface.		Yes	Yes
`declare-use`	Rare, since most called interfaces are defined externally.	Yes		Yes

Concern Element

Concern elements bind individual units to hyperspace dimensions outside their Java class hierarchy. Concern elements permit cross-referencing and validation of the universe of composition. The concern element has only two attributes, dimension and coordinate. Concern elements are nested elements of an interaction unit.

A concern annotations takes the following form:

//<- concern dimension="dimension" coordinate="" />

Note that the a unit annotation for a concern element uses the "-" gather marker and that it defines an empty element using the /> terminating sequence.

Unit Form Attribute Values

The form attribute defines the form of each software unit.

For Java, the following unit forms are recognized:

`form` Attribute Values	Description
`class`	The annotated unit is a class.
`ctor`	The annotated unit is a class constructor.
`method`	The annotated unit is a method.
`field`	The annotated unit is a field.
`static method`	The annotated unit is a static method.

Future work may support automated collection of this attribute though analysis of the Java source code.

Interaction Mode Attribute Values

The mode attribute defines the intended interaction mode for this unit. Each interaction mode defines a specific set permissible composition behaviors. The two basic composition modes are fusion and dispatch. Some extended and aggregate composition modes are also supported (e.g. singelton, after, before).

The following interaction modes are recognized:

`mode` Attribute Values	Compostion Behavior
`fusion`	Combine with other compatible fusion units.
`dispatch`	Combine with other compatible distpatch units.
`singleton`	Do not combine with any other unit.
`before`	Combine with other fusable units, subject to an ad hoc ordering restriction.
`after`	Combine with other fusable units, subject to an ad hoc ordering restriction.
`staged unit`	Combine with other fusable units, subject to an defined ordering restriction.

Dimensional Mode Element Values

The following dimensionsal modes are recognized in dimension.xml files:

Element Value	Intent
`Enhancement`	The dimensions defines a set of largely independent units. Any dependencies are based on `<define>`, `<extend>` and `<use>` declarations.
`Staged`	The dimension defines a sequences of named stages. Executable can be bound to each stage.
`Selection`	Call an interface or `get()` a variable value.

Page design by Pnambic Computing.