Design Review

1. Overview

APT is being designed to be as general purpose as possible. To achieve
this the architecture is broken down into three distinct, packages:
Tina, APT, and HST APT, from most generic to most specific.

2. Layered Framework

The architecture of Tina, and therefore of APT and the HST
implementation of APT uses four layers or tiers. Each layer is built
upon, and dependant upon the layers below it. The first layer is the
persistent storage for proposals which is currently via XML files on
the local file system. The second layer is the APT data model as a
domain specific extension of the Tina data model. The data model
understands and uses and the underlying storage layer.

The third layer is the controller, which depends upon the Tina data
model of which the HST proposal data model is an implementation. APT
tools communicate with the controller, and make use of the data model.

The fourth layer is the GUI or view which presents an interface for
interacting with the controller and data model. APT tools provide GUi
components that are plugged into the top level browser.

3. APT Tools

Tools for APT are required to implement the TinaToolController
interface, or to extend the AbstractTinaToolController class which
provides default implementations of most of the interface methods.

Tina Context

A central component of the Tina system is the context, an instance of
TinaContext. The primary role of the context is to convey user object
selection to the tools. In addition, the context maintains other
attributes of the selection:

* user selection: The set of objects selected by the user in the
  hierarchical editor.

* inferred selection: Tool specific selection of additional objects.
		Any tool can set the inferred selection, and tools may
		decide whether or not they react to the inferred
		selection. The hierarchical editor will set the
		inferred selection to the objects contained by the
		user selection.  The spreadsheet editor will listen to
		the inferred selection and display it.

* lead selection: The primary or lead selection. This is the primary
		selection within the overall group of objects that is
		selected. Any tool can set this attribute, and any
		tool can read it. The hierarchical and spreadsheet
		editors will set this to the most recently selected
		object. The spreadsheet editor will select this object
		unless the selection is set within another view of the
		spreadsheet editor itself.

* proposal selection: The currently selected proposal. Saving, and undo
		and redo are tied to the current proposal.

Tina/APT Tool Interface

Tools are designed to plug into the system framework via a generic
tool interface called TinaToolController. We also supply a default
implementation of this interface in the abstract class
AbstractTinaToolController.

This interface provides methods that describe the tool for the Tina
framework, allow that framework to pass the Tina Context to the tool,
and allow the controller to obtain GUI views from the tool to place
into the browser and preference window.

The tool describes itself to Tina via the methods:

* getToolName: Returns the full name of the tool to be used in the
  tools menu.

* getToolShortName: Returns a shortened name to be used in the tool
  bar.

* getToolTipText: Returns a longer string describing the tool more
		fully. This will be used as the tooltip for the tool.

* getToolIcon: Returns an icon that may be used in either the menu or
  the tool bar.

Interaction with the Tina controller is via a number of methods:

* activate: Called when the tool is made active and its view is made
		visible by placing it into the browser.

* deactivate: Called when the tool is made inactive and its view is
		hidden by removing it from the browser.

* setContext: When the tool is first loaded into the Tina framework it
		will be passed the context via this method.

* getComponent Should return the GUI component to place into the
		browser. As described below, additional calls should
		generally return a new view, not the same one.

* getPreferencePanel Should return the preference GUI panel to be
		placed in the preferences window. Null may be returned
		if a tool has no user defined preferences.

A tool will generally implement the TinaContextListener interface, and
when given a TinaContext the tool would register itself as a
listener. This interface defines a single method that is called
whenever the context changes:

* contextChanged Notification that the context changed. As there is
		only one instance of the context, no event is
		necessary as the listener can simply query the the
		context.

TinaToolController is an extension of the interface TinaQuitListener
which defines an interface for the Tina controller to notify
interested listeners when the system is about to quit:

* tinaWillQuit: Called just before the system quits allowing tools to
		clean up before exiting.

Tool activation and deactivation

A requirement of the system is that tools in the background not impact
the responsiveness of the foreground tools and browser. We have
decided to use the java event model to support data model and context
change notification. This means that the main system thread will be
processing the callback into the tools when these changes occur. As a
result we will meet the above requirement by convention, ensuring that
the tools return quickly from these callbacks.

Placing the burden on the tools to consume minimal CPU in the
background means that they need to know whether they are foreground or
background. This notification is achieved through the activate and
deactivate methods. When a tool is activated it should make itself
consistent with the current context, and with the state of the objects
in the context. When it is deactivated it may need to defer responding
to data model and context changes.

If a tool is very fast then it may be able to essentially ignore the
activation and deactivation. This may also apply when the tool
requires a specific use action, such as a button push, to 'run'. Other
tools may need to go to more effort to defer processing.

4. Tool Design Pattern

Intent: To ensure separation of views from tool controls and models
thereby supporting multiple views into a tool.

Motivation: Flexibility. We have already found that having two
instances of the Spreadsheet Editor open simultaneously has some
value, however we do not want two full implementations of the tools at
once. Rather we would like to have multiple views into a single tool
for performance and memory use reasons. We believe that there will be
more instances in which it is desirable to have two or more views and
this design pattern separates the computational logic and state of the
tool from the GUI display associated with the tool.

Structure: The pattern has three elements: an implementation of the
TinaToolController interface, a GUI component that provides a view of
the tool, and a listener interface through which multiple instances of
the view are notified when the tool changes. The view implements the
listener interface and each time a new view is created it is
registered with the tool controller as a listener. This pattern was
used in the implementation of the current set of built-in tools.

The tool controller interface may be implemented by the core tool
itself, or may by a wrapper around the tool. In either case the tool
should defer full initialization until the first time it is activated
via the activate method. The Tina framework will not call getComponent
until after the first activation of the tool, but the tool controller
will be instantiated at APT startup time.

This pattern supports the following:

  * startup of the tool without full initialization

  * notification when initialization is necessary

  * separation of the tool from the GUI

  * multiple simultaneous views of a single tool