Tools for Hyper/J Composition

Quick Start and Installation

Hyperspace Organization Scheme

Universe Construction Toolkit

Unit Annotations

The organizational scheme standardizes the names and the locations of hyperface features within the conventional Java class hierarchy. All composable classes are defined and implemented in leaf packages. These packages define the modules of composition and the coordinates in the hyperspace. Higher level packages organize modules into components. For most modules, the immediate parent component defines a hyperspace dimensions for all of its children.

The toolkit gathers information from the organizational scheme, and summarizes it into a comprehensive hyperspace.xml file. This XML file servers as a database of available dimensions and concerns. Current tools automatically generate the Hyper/J files needed for a basic composition.

The basic organization scheme is a simple extension of the Java class hierarchy. As such, it can only capture hierarchical concerns and relationships. Non-hierarchical relationships require the capture of addition information. The experimental Unit Annotations provide a means to define wide-ranging, non-hierearchical relationships. Currently, the toolkit collects Unit Annoations, but does not process them. In the future, the toolkit is expected to use the annotations to analyze and validate the universe of composition.

These tools are also described in the paper Simplified Universe Construction for Hyper/J Composition, currently in draft form. It is expected for submission to the workshop on Tools Support for Aspect Oriented Software Development at OOPSLA'02.

This implementation relies on Perl, Java, and an XSLT processor. For the Windows platform, the ActiveState ActivePerl release and Michael Kay's Saxon XSLT releases appear to work well. Java is needed only to execute the Saxon XSLT processor. The Sun 1.4 JRE works fine. You must have Perl and Java available from the standard path.

After unpacking the HyperJTools.zip file, you will need to change the xlst.cmd file to point to your XSLT installation. You may also want to add the HyperJTools installation directory to your PATH environment variable. Unix user's will need to adapt the DOS scripts to their preferred command shell.

The toolkit recognizes dimensions and coordinates by the presence of dimension.xml files. You will need review your Java class hierarchy and add one or more dimension.xml. You do not need to follow the naming conventions of the standard organizational scheme.

Run the Gather.pl file to build a hyperspace.xml file. After this file is generated, you can create the Hyper/J specification files by running the genHyperspace.cmd, genConcernMapping.cmd, and genHypermodule.cmd command files.

A typical usage sequence is:

C> Gather.pl . > hyperspace.xml

C> genHyperspace hyperspace.xml > Composite.hs

C> genConcernMapping hyperspace.xml > Composite.cm

C> genHypermodule hyperspace.xml > Composite.hm

C> hyperj -hyperspace Composite.hs -concerns Composite.cm -hypermodules Composite.hm ...

The roles of component packages are more varied. The bottommost level of components collects the module packages into hyperspace dimensions. Higher-level components contain only other components. Subsystem components control interface boundaries. A typical package hierarchy follows this pattern:

package compSubsystem
   package compComponent
       … nested components
      package compDimension
         dimension.xml
         package modModule

In this project organization, all unit implementations are at the lowest level of the package hierarchy (in module packages). All dimension are defined in the component packages that immediately contain the module packages. The dimension.xml file that accompanies the Java source files distinguishes these dimension packages.

These naming conventions (compComponent and modModule) are not enforced by the toolkit. A more fine-grained convention might include subsysComponent or dimComponent names for specific component categories. With some planning, these naming conventions might be entirely ignored. However, this document uses these conventions widely.

Each dimension.xml file identifies a package that represents a dimension. Each Java package within a dimension component defines a coordinate within the dimension. For a Platform dimenesion with four nested modules might define the modBasic, modConsole, modExit, and modProgName coordinates.

A dimension.xml describes the hyperspace dimensions for its owning package. These XML files provide a name and a descriptive summary for each dimension. The Platform dimension can be described with the following dimension.xml file:

<?xml version="1.0"?>
<dimension>
   <name>Platform</name>
   <summary>Execution Platform support</summary>
   <mode>Enhancement</mode>
   </dimension>

The <name> element defines the dimension's label, and the <summary> element provides a descriptive text. These are used in generated outputs to define Hyper/J dimensions.

The <mode> element documents the intended interactions for the modules within the dimension. This element is intended for validation with Unit Annotations. The currently recognized mode values are Enhancement, Selection, and Staged. These are described in more detail in the Annotation References page.

The gather application (Gather.pl) walks a Java source tree and builds a hyperspace.xml file that is used for further processing. The basic content is an XML rendition of the package hierarchy, with embedded dimensional information (from the dimension.xml files). The gather application also inspects .java source files for unit annotations. Any unit annotations are added to the hyperspace.xml .

At present, generators are available for Hyper/J's hyperspace specification(.hs), concern mapping(.cm), and hypermodule specification (.hm) files. These generators use the Saxon XSLT processor to reformat the composite.xml content for Hyper/J. Additional generators can implement cross-referencing or validate composition intent.

The gather application produces a hyperspace.xml that summarizes the universe of composition. This file is a standard XML format with the following elements and attributes:

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

Additional elements are introduced by the dimension.xml files and source file unit annotations. The dimension.xml elements include dimension, name, summary, and mode elements.

No DTD or XSchema for validation is currently available. The current tools do not support XML Namespaces.