			APT Data Model
			==============


Overview
--------

APT is the Astronomers Proposal Tools. It is a tool for preparing an HST
observing proposal (i.e. Phase 1 and Phase 2), but it is also a framework for
plugging together an APT document, and a set of tools to view and edit the
document.

The APT Framework will adhere to the Model-View-Controller (MVC) design pattern.
The purpose of this design pattern is to strictly separate the underlying data
model from the graphical views of that data, with the controller providing the
logic that binds the two and translates user input into model behaviour. The
advantage of this approach is that it is straight forward to change, replace
or add views without having to change the model, and often without having to
change the controller.

* The model, is the repository of the data that forms the document (I am using
  document as an generic term, which for APT I assume to be a proposal). 

* The view is the presentation and interface to the document presented to the
  user - generally the GUI.

* The controller is the logic that binds the view to the model and which manages
  user input.


APT Structure
-------------

APT will be composed of the APT core, a set of plug-in tools, and a self-
describing plug-in document model. We expect that the structure of an APT 
installation will look something like:

+-<Install Location>
  +-APT
    |-Run APT
    |
    +-Documentation
    |
    +-Tools
    | |-VTT.jar
    | |-ETC.jar
    | |-Spreadsheet.jar
    | |-Heirarchy Editor.jar
    |
    +-Document Model
    | |-HST Proposal.jar
    | +-Templates
    |   |-Visit Templates.xml
    |
    +-Classes
      |-APT.jar
      |-util.jar
      |-whateverelse.jar

For HST APT, we will be supplying the complete bundle including the APT core,
the HST proposal data model and a set of tools to view and edit instances of
the proposal. The architecture is generic enough to support other uses. In 
particular, it will easy for other observatories to extend APT for their own
use through plug-in data models and tools.


The Document Model
------------------

The most generic view of an APT document is that it is a hierarchy of objects
with editable properties. The two default tools in APT are built to manipulate
the document at this level. The heirarchy editor displays and edits the
heirarchy, and the spreadsheet editor displays and edits the properties of the
objects.

The properties of the component objects will be exposed by making the proposal
objects into Java beans. This allows a generic editor to determine through
introspection the public properties of an object and to support editing of
those properties. The spreadsheet (tabular) editor will present objects as rows 
within a table, with the cells displaying object properties and supporting
editing of those properties.

The hierarchy of the proposal will be displayed and manipulated in the
heirarchy editor. A new interface will be required which will allow the
proposal objects to describe their editable tree structure. In  addition to
the MutableTreeNode interface, the proposal objects will be required to supply
information about the specific classes that may be instantiated directly below
them in the heirarchy.

A third interface that the proposal model must support is the control interface
between the root node of the proposal and the APT core. This interface supports
the loading and saving of the proposal, undoing and redoing changes, and so on.


Proposal Hierarchy
------------------

For the HST proposal the hierarchy will look something like:

-Proposal 1223
 +-Proposal Information
 +-Targets
 | |-Fixed Target 1
 | |-Moving Target 2
 | |-<New Target>
 |
 +-Pattern Specifications
 | |-Pattern Spec 1
 | |-<New Pattern Spec>
 |
 +-Visits
   |-Visit 1
   | |-Exposure 1
   | +-Pattern 1
   | | |-Exposure 2
   | | +-Parallel
   | |   |-Exposure 3
   | |   |-Exposure 4
   | |
   | |-<New Exposure>
   | |-<New Collection>
   |
   |-<New Visit>

To support editing and display of the document hierarchy, the nodes of the
hierarchy must implement an interface that provides:

* A test for whether the node is a leaf node or not.
* A description of the new objects (if any) that can be created within the
  node.
* What object types they are drag-and-drop targets for.
* Whether they have properties that can be manipulated in the spreadsheet
  editor. 


Proposal phases (Phase 1 vs. Phase 2)
-------------------------------------

The HST proposal submission process occurs in two phases, with different data
required during each phase. The current proposal preparation tools require a
certain amount of duplicate information to be entered in phase 2. We propose
to eliminate this redundancy by making a phase 2 proposal a direct, and natural
extension to a phase 1 proposal.

The proposal will supply a list of editing phases (or modes) to the APT core.
If a set of phases is supplied then APT will provide a menu of phases to the
user, and will include the currently selected phase when inspecting the 
proposal. This will allow the proposal to present different descriptions of
itself in different phases.


File Format
-----------

Proposals will be saved to disk for persistent storage using XML. The first
version of the HST Proposal Document Type Definition (DTD) is attached. The
use of a DTD allows the XML parser to validate the file as it is read. This
is important as we expect that some users will choose to manually edit the
proposal file. We also anticipate that in the long term, this XML file will
be the product that is submitted to STScI by the PI.


Templates
---------

Templates are canned instances of proposals and proposal objects. A library
of templates will be supported via a set of proposal files in the document
model subdirectory of the APT installation. The default installation will
supply a set of templates which can be added to by the user.

The files will be the same format as proposal files and their location will
allow APT to treat them as templates. As proposals they will be editable
using all of the APT tools, which will require no special knowledge of their
status.


Attachments
-----------

1. UML class diagrams for the APT top level, and HST Proposal.
2. DTD for the proposal file format.
3. An example proposal in XML format.
