# 
# * See the file "PlanWorks/disclaimers-and-notices.txt" for 
# * information on usage and redistribution of this file, 
# * and for a DISCLAIMER OF ALL WARRANTIES. 
# 

# $Id: README,v 1.146 2005/06/14 15:39:37 pdaley Exp $
#

NOTE: Due to some SQL syntax irregularities, MySQL 4.0.20 fails to correctly
construct the PlanWorks database.  Do not use this version of MySQL.
The current known-good MySQL versions are:
4.0.13
4.0.18
4.1.1
4.1.7

SUMMARY (PW_M_23)
=================

WARNING: MySQL database change in this release. Execute:
         'ant planWorksDbInstall' begore running PlanWorks.

o Horizon start of minus infinity causing a graphics exception.
  Now get horizon start and end from values TimeScaleView
  computes instead of constant minus and plus infinity
  that comes from the PPW generated tables.

o Fixed data type for LevelMax and LevelMin in the
  PlanWorks tables. Was doubel(11,30) which caused
  a problem for at least one version of MySQL. Changed
  to decimal(15,5) which is in line with range of 
  possible values.

o GNATS PRs and CRs:
  #2961: sun.dc.pr.PRException in resource views 

CVS CHECKOUT
============
Latest development state:
  > cvs co PlanWorks  or
  > cvs update PlanWorks
Latest tagged milestone: (see Summary above)
  > cvs co -r PW_M_23 PlanWorks


PLATFORM REQUIREMENTS
=====================
Mac OSX - three button mouse is required.


PREREQUISITES
=============
Set environment varibles:

  o JAVA_HOME - location of J2SDK >= 1.4.1 or higher
    On Solaris (Code IC)
      setenv JAVA_HOME /usr/local/j2sdk1.4.2_05
    On Linux, e.g.
      setenv JAVA_HOME /home/wtaylor/pub/j2sdk1.4.2_04
    On MacOSX, in terminal window
      setenv JAVA_HOME /System/Library/Frameworks/JavaVM.framework/Home
      or, put this statement in
      $HOME/.MACOSX/env.plist

  o PATH - should include Ant 
    e.g. tcsh: set path = ($path /home/wtaylor/PlanWorksProject/PlanWorks/java/lib/apache-ant/bin)

  o OSTYPE - linux, solaris, or darwin (MacOSX)
    Should be set by user's standard environment (may need to be set locally on
    MacOSX to "darwin", since global setting maybe "darwin7.0")

  o USER - user's account name, used in defining the data base collection
    Should be set by user's standard environment

  o PLANWORKS_HOME - path to this directory
    On Linux, e.g.
      setenv PLANWORKS_HOME /home/wtaylor/PlanWorksProject/PlanWorks

  o CLASSPATH - should be the empty string( actually this is a requirement for PLASMA).


OPTIONAL CONFIGURATION
======================
o The default value for the maximum memory required by the Java Virtual 
  Machine is 200 mega-bytes.  It is posible to set it to a much higher 
  value, but only to this one particular value (Ant is reponsible for 
  this restriction):

  > setenv JVM_GC_MAX 975


BUILDING THE PARTIAL PLAN WRITER
================================
The PartialPlanWriter is included in the standard PLASMA build.


BUILDING & RUNNING PLANWORKS
============================
If you're running Solaris 8, everything should work right out of CVS.  
Just follow the instructions below.  

If you're running Linux, you'll have to download the MySQL binary release 
version 4.0.13 or higher for your system. MySQL is open source. Download from:
     http://dev.mysql.com/downloads/mysql/4.1.html
NOTE: MySQL 4.1.8 is known not to work with PlanWorks.  The latest known good
version of MySQL is 4.1.1.  

Download the version for your specific platform, un[zip|tar] it, and copy 
the "mysql", "mysqld", and "mysqladmin" executables from the bin directory 
into PlanWorks/lib/mysql/bin. 
Also, overwrite the files in PlanWorks/lib/mysql/share/mysql/english/
with the files in /path/to/your/mysql/share/mysql/english/.  

Alternately, if you have an existing MySQL binary installation and wish to use
that, you can do so by editing build.xml, setting the property
"mysql.custom.bindir" to point to the directory containing the binaries,
then commenting out the line in which the property "mysql.bindir" is set
for your operating system in the chk_[linux|solaris]_2 targets.
If you run 'ant planWorksTest', you have to hit C-c to exit the testing
after it prints its report.  Also, it is strongly recommended that you run
'ant cleanDb' after the tests to make sure the test data is purged from
the database.

Only one instance of PlanWorks may be run concurrently, due to interactions 
with MySQL.

> cd PlanWorks

> ant planWorksDbInstall # this sets up the database and must be run before
			 # anything else

> ant createJNI # this creates the JNI interface to integrated planners       

> ant # default is to run the application with compilation of all PlanWorks
      # Java source as a dependency.

> ant -projecthelp # lists available targets

 cleanCls           -- delete the 'java/classes' directory tree
 cleanDb            -- delete loaded projects from data base, unless -Dno.clean.db=yes
 compile            -- compile 'java/src' tree into 'java/classes' tree
 createJNI          -- create the JNI interface to Planners (compile dependency)
 createJars         -- create PlanWorksDB.jar and PlanWorksPlugin.jar in ./java/jars
 planWorks          -- run PlanWorks application (compile dependency)
 planWorksDbInstall -- create all necessary databases and tables
 planWorksProf      -- run PlanWorks with profiling info
 test               -- All PlanWorks tests, including JFCUnit test (compile, cleandb dependencies)

Default target: planWorks


THE JNI INTERFACE TO INTEGRATED PLANNERS
========================================
The ant "createJNI" target creates
${PLANWORKS_HOME}/cpp/integration/PlannerControlJNI.h
and compiles it with
${PLANWORKS_HOME}/cpp/integration/PlannerControlJNI.cc
to generate
${PLANWORKS_HOME}/cpp/integration/libPlannerControlJNI.so
which is loaded by "Project->New Sequence".


USER DOCUMENTATION
==================
See file "PlanWorks/GETTING_STARTED" for PlanWorks usage.


TESTING DOCUMENTATION
=====================
See file "PlanWorks/testCases/planViz.txt" for testing use cases.


PREVIOUS MILESTONES
===================
===================

1june2005: Milestone 22
=================

o Added Set Timescale Line for EARLIEST and LATEST timelines. 
  These views are accessed via the right mouse click pop-up window. 

o Scale down the width of the token nodes for EARLIEST and LATEST
  timelines.

o Zoom only the horizontal scale for all timeline views.

o GNATS PRs and CRs:
  #2884: ground timeline view with min and max values

19may2005: Milestone 21
=================
o Added two new views to the Timeline View to show EARLIEST and
  LATEST timelines. These views are accessed via the right mouse
  click pop-up window. The default window is the show INTERVAL
  timeline view which is unchanged from prior releases.

o GNATS PRs and CRs completed:
  #2884: ground timeline view with min and max values

18may2005: Milestone 20
=================
o GNATS PRs and CRs completed:
  #2904: removed Decision View from menu
  #2924: check for null rule path 

08december2004: Milestone 19 
=================
o Removed check for a valid path when configuring the model output 
  destination directory in the Configure Project and the Configure 
  New Sequence dialogs. It is not a requirement for this directory 
  to exist ahead of time. If it does not exist, it will be created 
  by the planner.

o GNATS PRs and CRs completed:
  #2686: model not unloaded when planner exception occurs.
  #2687: model is not terminated and unloaded if user closes Planner 
         Control window.
  #2688: waits forever when planner returns with "search exhausted" code.
  #2689: final plan status not displayed after planner completes.
  #2690: Planner Control window does not display planner "running" status.
  #2691: setting "write step" or "write next" past last step handled
         poorly. Model is not unloaded, plan status not displayed.

14october04: Milestone 18
=================
o Ant target 'createJNI' has been added to create the shared library 
  "libPlannerControlJNI.so" which PlanWorks loads when it processes
  "Project->New Sequence".  "Project->Configure" and "Project->New Sequence" 
  both have a settable parameter named "planner path", which is the planner's
  shared library loaded when processing "Project->New Sequence".


o GNATS PRs and CRs completed:
  #2541: Sequence Query Results tables, when sorted, do not find object key entry.
  #2544: Token Network View's redraws do not do layout.
  #2593: Move rule delimiter chars into configuration.

22september04: Milestone 17
===========================
o "Project->Configure" and "Project->New Sequence" have been added to support
  integration with PLASMA.  The "Planner Controller" window allows the user
  to run plans with PLASMA and view the results in PlanWorks.

o Background Mouse-Right "Find Entity Path" in the Token Network, Constraint
  Network, and Navigator views, now highlights the appropriate links, as well
  as the nodes.

o In the Resource Profile View, Mouse-Right "Rescale '<resource-name>' Profile" over
  a resource profile will allow the user to enter new x, y minumum and maximum
  values and create a new view of the selected resource.  It is also possible to
  "Reset" the created "unary" resource view to its original scaling.

o All partial plan views, and Content Filter dialogs now have the background 
  Mouse-Right selections: "Step Backward All Views" and "Step Forward All Views" 
  which "step" all active views for the partial plan step upon which it is invoked.


o GNATS PRs and CRs completed:
  #2556: Scale for resource view.
  #2566: Find Path should highlight links.


26august04: Milestone 16
========================
o PlanWorks now reads a configuration file during start-up, and supports a
  Java plugin capability.  See README.ConfigureAndPlugins.

o If you are using PlanWorks with PLASMA, this revision requires PLASMA
  from the CVS head.  The PartialPlanWriter has been modified to capture
  rule instances.

o Usage of the test language requires an updated version of MySQL.  You 
  *must* be working with MySQL 4.1 or later.

o The Token Network View handling of rules has been revised:
  - Mouse-Right: "Rule Window" on the view background has been removed;
  - links between token nodes are no longer mouse sensitive;
  - rule instance nodes, rendered as ovals, with the instance key and the
    rule key values in the label, now are linked bewteen token nodes;
  - Mouse-Right on the rule instance nodes brings up the selections "Open
    Constraint Network View", "Open Navigator View" and "Open Rule Instance View".  
    Selecting the third creates an internal frame titled "RuleInstanceView of 
    <plan-name>/stepnn - n", which displays the "from" token, and "to" token key 
    values and predicates, followed by the text of the rule;
  - A "RuleInstanceView ..." internal frame may be created for every rule instance
    node in the Token Network View;
  - Mouse-Right: "Close Rule Instance Views" on the view background has been added.

o Rule Instance nodes, which have variables, now appear rendered as ovals in the
  Constraint Network View.  Rule Instance nodes are now included in the Navigator
  View.  "Open Rule Instance View" is available as a Mouse-Right selection on these
  nodes.

o "Help->Node Shapes" has been added to the PlanWorks menubar.  It will create a
  top-level window, separate from the PlanWorks desktop, which shows the shapes
  of the different nodes rendered in the partial plan views.

o The first version of the Test Definition Language has been completed. The
  specification is located at PlanWorks/doc/TestLangSpec.txt.  It can be
  accessed through Project->Run Test

o PlanWorksGUITest now supports tests 1-11 of 25, defined in testCases/planViz.txt

o The sequence directory chooser now supports the selection of a directory,
  whose children are all sequence directories, so that user multiple directory 
  selection is not necessary.

o "Progress monitors" have been added for functions which can be cpu intensive, such
  as creating partial plans and rendering views.  The user has the option to "Cancel" 
  these operations, if desired.

o Added new Ant target 'createJars' which creates PlanWorksDB.jar and PlanWorksPlugin.jar
  in PlanWorks/java/jars.  (These jar files are checked in to CVS).

o The TokenNetwork View is now incremental -- it opens with the "root" tokens and t
  heir immediate rule instance nodes.  They can be expanded incrementally as in the 
  Navigator View.  The layout is maintained when "stepping".

o The PLASMA PartialPlanWriter configuration file now resides at
  PLASMA/CBPlanner/component/sample-ppw-config.  Your PPW_CONFIG environment variable
  should reflect this change.

o The PLASMA PartialPlanWriter (PPW) can now output a plan with complete transaction 
  and statistics files, but with only the last step's partial plan files.  Put the
  following lines are in your PPW configuration file:
    AutoWrite=0
    StepsPerWrite=1
    WriteFinalStep=1 

o PLASMA can now be run with interactive control over which step's partial plan files
  are output.  This is done using gdb.  See PLASMA/CBPlanner/component/ppw-gdb-commands.

  NOTE: There is a naming issue with the these commands.  gdb 6.1.1 requires full
  namespace qualifications (Prototype:: and Prototype::PlanWriter::).  gdb 5.2.1-4 does
  not work for any combination of qualifications.  gdb 5.0 requires no namespace 
  qualification of any sort (it seems to completely ignore namespaces).

o The Constraint Network View, the Token Network View, and the Navigator View have
  two new background Mouse-Right selection options: "Find Entity Path" and
  "Highlight Current Path".  "Find Entity Path" requests two entity keys, class 
  node types to search, and an optional maximum path length.  "Find Path" finds a 
  path through the classes specified, rendering the selected nodes and highlighting them.  
  This dialog also offers "Does Path Exist" which determines whether a path exists, 
  without finding the nodes.  Selected nodes are dragged as a group, which may be 
  inconvenient.  To deal with this, click Mouse-Left in the background to discard 
  the selections, drag the nodes to new locations, and then on the background select
  Mouse-Right: "Highlight Current Path".

o The Navigator View has a new background Mouse-Right selection option: "Find by Key",
  which requests a single entity key and finds that node, opening it and its neighbors,
  if necessary.


o GNATS PRs and CRs completed:
  #2424: RuleInstance: Should be able to view from any RuleInstance node in any view.
  #2452: Right mouse click popup menu not supported by any nodes in Navigator View.
  #2473: Deleted sequences shouldn't kill PlanWorks.
  #2474: Extra empty node in DecisionView.
  #2514: Comments not being correctly parsed in the PlanWorks config file.
  #2538: Garbage Collection killing Tatianas machine on Resource Profile.


04june04: Milestone 15
=====================
o If you are using PlanWorks with PLASMA, this revision requires PLASMA
  version PW_PLASMA_1 or later.

o The partial plan DBTransaction View and the Sequence Query result views for
  Steps, Transactions, Free Tokens, Unbound Variables, and All Decisions - have
  all been reimplemented using Swing JTable, instead of JGo widgets.  A
  significant performance improvement has been realized, and additional
  capabilities now exist.  The table column widths can be resized by dragging
  the column header boundaries.  The row sorting by column values is now more
  advanced: Mouse-Left clicks cycle through sortAscending, sortDescending, &
  noSort - while clearing other column sorts; Control-Mouse-Left clicks cycle
  through sortAscending, sortDescending, & noSort - while not clearing other 
  column sorts.  "Find Object/Token/Variable by Key" is available with
  Mouse-Right, where appropriate, on the panel between the window title and the
  table header.  Mouse-Right on "Step" column cells offers to open partial plan
  views for that step.

o The PLASMA PartialPlanWriter now uses a configuration file and one environment
  variable rather than a set of environment vars.  Set the PPW_CONFIG environment
  variable to the path of the configuration file you want.  A sample configuration 
  file is available at PLASMA/System/component/sample-ppw-config.  The GeneralConfigSection 
  is for things like allowing the PPW to write automatically, how often it should write,
  where it should write, and how many choices should be written per decision.  The
  TransactionConfigSection is a list of all of the transactions that should be logged.
  A '#' as the first character on a line causes the PPW to ignore the entire line.

o The Decision View has been added which lists the current plan decision and pending 
  decisions in a "tree" format.  Decisions with choices are "openable".  Objects, 
  resources, timelines, interval tokens, resource transactions, and variables can be 
  viewed in other appropriate views by choosing from Mouse-Right click selections
  on decision and choice entity key values.  A Mouse-Right click on the background 
  offers the user "Find Decision by Key" and opening other views, as choices.

o Previously, the DB Transaction View was not "steppable".  It now is, as are all the
  other partial plan views.

o The PlanWorks "Window" pull-down menu of all active windows is now ordered thusly:
  - menu separators divide different plan sequence window groups;
  - within each plan sequence group, the ordering is SequenceQueryView, SequenceStepsView,
    and any QueryResults windows;
  - then a cascading sort by step number, and by view name of all partial plan views,
    including the NavigatorView.

o  GNATS PRs and CRs completed:
   #2332: Need resizable column width in DB transaction view.
   #2385: Crash while trying to sort transactions by name in the DBTransaction window.


14may04: Milestone 14
=====================
o This release *does* require a total rebuild of the PlanWorks data base,
  using "ant planWorksDbInstall".  All plans to be loaded must be
  regenerated using the PartialPlanWriter.

o Beginning with this version, there is no up to date PartialPlanWriter 
  support for Europa, and thus no support by PlanWorks.

o Mouse-Right "Zoom View" has been added for the Constraint Network, 
  Navigator, Temporal Extent, Timeline, and Token Network partial plan 
  views.  It also is available in the Sequence Steps view.  The zoom 
  out factors are x2, x4, x6, and x8 (the same scaling as the Overview 
  views).  Whereas Mouse-Right "Overview Window" creates a new window and
  allows the coordinated  viewing of the paired windows, "Zoom View" 
  does not create a new window, rather it changes scaling in the 
  existing window.  Thus the existing Mouse-Right functionality on
  the view background and the view nodes is maintained.

o The Sequence Steps View now has Mouse-Right "Step Backward step<nn> 
  Active Views" and Mouse-Right "Step Forward step<nn> Active Views",
  where <nn> is the currently selected step. Active views are those views
  which exist for the currently selected step.

o In the Sequence Steps View above each histogram step is a colored dot: 
  green - partial plan loaded into data base; yellow - partial plan on 
  disk; and red - partial plan not on disk.

o The Token Network View now has a Mouse-Right selection "Rule Window",
  which will bring up a window, such that when it exists, moving the 
  mouse over the view's token node links will present in the "Rule View 
  for <sequence-name>/step<nn>" window, the "from" and "to" token predicates 
  and parameter lists, their keys, and the model rule which is responsible. 

o The model rules shown in instances of "Rule View for <sequence-name>/step<nn>"
  are loaded from the appropriate NDDL model.

o The "test" target of ant now runs, in addition to the BackendTest, the MySQLDBTest,
  and the PlanWorksUtilsTest, the PlanWorksGUITest which is an implementation
  of 10 of the 23 tests defined in PlanWorks/testCases/planViz.txt.  The
  JUnit and JFCUnit packages are used in the PlanWorksGUITest implementation.

o  GNATS PRs and CRs completed:
   #2238: unable to build planworks.
   #2335: Exception dialog box with no description.
   #2345: Variables in the Plan seem to have many possible values while the planner 
          output shows singletons.
   #2375: RELAXATION TRANSACTIONS not listed in query by transaction type.
   #2376: The Query results display the transaction types. Some are too long for 
          the space.
   #2389: Crash when quickly stepping in Timeline view.
   #2390: Cannot scroll window to end of object at far right of view.
   #2398: Transaction types too long for space: Query-Steps-Where Variable Transacted.


10march04: Milestone 13
=======================
o This release *does* require a total rebuild of the PlanWorks data base,
  using "ant planWorksDbInstall".  All plans to be loaded must be
  regenerated using the PartialPlanWriter.

o Automatic location offsets for partial plan views and Content Filter
  windows will no longer be used -- the user will relocate overlaying 
  windows manually.

o The SequenceStepsView has these Mouse-Right selections: "Close/
  Hide/Show <sequence-name>/step Views", which will close/hide/show 
  the partial plan view and Content Filter windows for all sequence
  steps.

o The Partial Plan Navigator View has been generalized to handle Objects,
  Timelines, Resources, and Resource Transactions along with their variables.

o Two partial plan resource views have been added: ResourceProfileView and
  ResourceTransactionView. Mouse-Right on their "extent" backgrounds allows
  the setting of a vertical time mark.  If both views are active for the
  same partial plan, the time mark is rendered on the companion view, which
  is scrolled so the time mark is in the view port.  The Mouse-Right selection
  "Snap to Active Resource Transaction" (on the ResourceTransactionView) and
  "Snap to Active Resource" (on the ResourceProfileView) will find and scroll
  into view the appropriate Resource or Resource Transaction, providing the
  "active" token is a Resource Transaction, rather than an Interval Token.


o  GNATS PRs and CRs completed:
   #2080: Require capability to visualize resource envelopes and transactions.
   #2184: build does not work due to bad mysql.bin dir in build.xml.
   #2198: Provide queries of constraint execution and when domains become emptied.
   #2235: Over-zealous invariant test in Timeline data.
   #2237: ColorStream not returning correct colors.
   #2241: Timeline view disappear and does not reappear after the 
          non-monotonic timeline error message.
   #2242: Script to clean database does not work correctly.
   #2243: Prototype:Planworks bug: Timeline view crash.
   #2244: Change Request: Not crash if a model's seq directories have been deleted.
   #2246: Not showing object names when variable is an object var.
   #2247: PartialPlanWriter outputting screwy data.
   #2248: Fix interaction between content filter persistance and state switching.
   #2249: Partial Plan View frames do not maintain user's resizing when stepping.
   #2250: Always show timeline objects in Timeline View.
   #2251: Keep Content Filter frame and view frames in same position when stepping.
   #2252: When stepping, move SequenceSteps View highlight to current step.
   #2256: SequenceStepsView: add hide/show all partial plan views.
   #2285: PLASMA:PPW: Incorrect data about merged tokens being displayed.


20january04: Milestone 12
=========================
o In the Temporal Extent View, Mouse-Right on the background now offers
  "Show Earliest" and "Show Latest", as options to "Show Intervals".
o A query for "All Decisions ..." at a step has been added to the "SequenceQuery" 
  window.  It brings up two results windows, one for free tokens and
  one for unbound variables.

o Speedups in database querying, Constraint Network View rendering, and
  Token Network View rendering.

o For all nodes, except empty slots, in the Constraint Network, the Temporal
  Extent, the Timeline, and the Token Network views, there is a 
  Mouse-Right selection "Open Navigator View" which allows navigation
  through all relationships in the partial plan data base.

o "Show All Views", the logical inverse of "Hide All Views", is now
   available in all situations where "Hide All Views" occurs.

o Content Filter specifications are maintained across partial plan view
  stepping operations.

o  GNATS PRs and CRs completed:
   #2186: Provide scoped viewing of information related to an item of interest.
   #2187: Use names of Objects rather than keys or provide a place to lookup 
          detail of item (like name) based on key.
   #2192: Snap to Earliest Start/Latest end in Temporal extent view.
   #2196: Provide integrated exploration view.
   #2205: Bad behavior when you try to switch to another project.
   #2206: Need ability to turn off auto outputing writing when using the planwriter.


30december03: Milestone 11
==========================
o Improved diagnostics for "Invalid Sequence Directory" error dialog.
o The "Find Transaction by Obj_Key" Mouse-right popup selection and
  the transaction entry column "OBJ_KEY", have now been properly
  restricted to the partial plan Transaction View, the "Steps"
  Sequence Query for "Where ..." queries with blank "Key" entries and
  "With ..." queries, and the "Transactions" Sequence Query for
  "In Range ..." queries.  The OBJ_KEY" value found using
  "Find Transaction by Obj_Key" is now highlighted.
o The Temporal Extent View now has an additional Mouse-Right selection:
  "Hide/Show Node Labels".  These node labels are now aligned with
  the earliest start times.
o The Content Spec dialog has been renamed Content Filter.
o The "window bar" buttons at the bottom of the DeskTop Frame have been
  removed.  Use the "Window" pull-down menu.
o The Constraint Network View's variable node tool tips have been
  augmented to show the PARAMETER_VAR names and OBJECT_VAR names.
o The Sequence Query dialog now has two new options: "Free Tokens At Step" 
  and "Unbound Variables At Step".
o Providing the Temporal Extent View is open for a partial plan step which
  has a Timeline View, Mouse-Right on the Timeline View background offers
  "Enable/Disable Auto Snap", which when enabled will cause the Temporal 
  Extent View's focus to follow the mouse cursor's movement over Timeline 
  View slots and free tokens.

o  GNATS PRs and CRs completed:
   #2087: Wierd behavior in constraint network.
   #2126: PartialPlanWriter breaks EUROPA make tests
   #2190: Align boxes in Temporal extent view with earliest start.
   #2191: Integrate Localized Temporal Extent Vizualization with Timeline/Token view.
   #2193: Provide stepping forward and backward capability for all views.
   #2194: Rename Content Specification to Content Filter.
   #2199: Provide actual parameter names.
   #2206: Need ability to turn off auto outputing writing when using the planwriter.


21november03: Milestone 10
==========================
o Sequence Steps windows are now closeable.
o Query Results windows are now maximizable.
o If the Content Spec window is iconified using the icon in the window's
  title bar, and the user selects Mouse-Right "Raise Content Spec", the
   Content Spec window is de-iconified and given focus.
o Partial Plan view's Mouse-Right selection "Open a View" no longer
  creates a seconday menu of views.  The available views are added
  "in-line" to the primary menu.
o Partial Plan view's Mouse-Right selections of views to open no longer
  includes the current view.
o The Content Spec window's background areas now offer Mouse-Right
  selections for opening individual or all partial plan views.
o The Sequence Query dialog for "Steps" queries now accepts an empty
  key slot, which will return the steps for all keys for the specified 
  contraint, token, or variable transaction type.
o The Sequence Query dialog no longer requires the use of the "Reset Query"
  button between successive queries.
o The object key values displayed in the Timeline view are now specified as
  to type: timeline, slot, and token.  The token key(s) are displayed as
  the second line of the slot node tooltip.
o Slotted tokens in all partial plan views, except for Transaction view,
  have a tooltip with a second line which displays their slot key value.
o Clicking on the "Apply Spec" and "Reset Spec" buttons of the Content
  Spec dialog cause the Constraint Network view to displayed with a
  fresh layout.
o The "Step" column values of Query Results windows for "Steps" and 
  "Transactions" queries, now offer a Mouse-Right popup with actions
  on the partial plan views for that step.
o The partial plan views, except for Transaction View, and the Sequence
  Steps View, now have a Mouse-Right popup named "Overview Window" which
  opens a 1/8th scaled view of the entire "observed" view.  There is a
  rectangle in the overview which can be dragged to cause the "observed" 
  view to be scrolled to new locations.  Mouse-Left clicking in the
  overview outside of the rectangle will cause the "observed" view to
  "jump" to that location.

o  GNATS PRs and CRs completed:
   #2169: Step query does not retrieve variable decisions.
   #2170: Exceptions thrown in deletion of a sequence.
   #2171: Possible source of error in PlanWriter.
   #2172: Invalid behaviour for sequence windows after closing and opening.


07november03: Milestone 9
=========================
The "Planning Sequence" menu now expands only into the available
sequence names.  Selecting a sequence name brings up two windows.
The first, "SequenceQuery ...", allows the user to make data base
queries over the sequence.  The second, the "SequenceStepsView",
is a histogram of the partial plan data base size for each step.  
Individual or all partial plan views for each step are available 
by clicking Mouse-Right on the desired step in the histogram.

The "SequenceQuery ..." dialog provides the user with queries which
are in two groups, based on the primary kind of information returned.  
"Steps": "Where Constraint/Token/Variable Transacted ..." which asks 
for a key value and the transaction type; "With Non-unit Variable 
Decisions", "With Restrictions", and "With Unit Variable Decisions".  
"Transactions": "For Constraint/Token/Variable ..." which asks for a key 
value; and "In Range ...", which asks for "StartStep" and "EndStep" values.
The query results are displayed in windows entitled "QueryResults for ...".
The query results windows can be removing by clicking Mouse-Right on 
the background of the "SequenceQuery ..." dialog, and selecting
"Discard Query Results Windows".

For each plan sequence step, there is now an additional partial plan
view: "Transaction View".  It displays the transactions for the step.

Both the partial plan "Transaction View" windows , and the sequence query
"Query Results for ..." windows for "Transactions" queries, and the
"With ..." "Steps" queries offer the user a pop-up dialog entitled 
"Find Transaction by Obj_Key".  Mouse-Right on the background of the 
header section of the window brings up this dialog.

The column header nodes of the "Transaction View", and "Query Results for ..."
windows, offer sorting of that columns's values, alternately in
ascending order and descending order.

All partial plan view's  Mouse-Right pop-ups offer the user a second
pop-up selection ("Open a View") of the other partial plan views, 
which will create them as needed.  All views, except for Transaction View,
also offer "Raise Content Spec", which will set focus on the appropriate
partial plan Content Spec window.

In addition, all partial plan view's  Mouse-Right pop-ups offer the user
"Close All Views", "Hide All Views", and "Open All Views".

Each partial plan view, except for Transaction View, had a Mouse-Right
choice of "Find Token By Key".  This has been changed and generalized to
"Find By Key".  For Temporal Extent and Token Network views, entered keys
will find token nodes; for the Timeline view, entered keys will find 
token and slot nodes; and for the Constraint Network view, entered keys
will find find token, variable, and constraint nodes -- opening
appropriate connecting nodes, if needed.

The Constraint Network View now uses a new layout algorithm that is many
times faster than the previous algorithm.  Layout now generally takes 
< 300ms.

Almost all loading of data into the database is deferred until absolutely
necessary.  This adds slight overhead to the first time a Partial Plan is
viewed, but is a one-time cost.

The current PartialPlanWriter (PlanWorks/cpp/integration/europa/README)
requires a recent version of EUROPA.  The earliest known working
version is tagged with the PlanWorks milestone release tag PW_M_9.  

The PartialPlanWriter has changed since PW_M_8, and must be rebuilt.

o  GNATS PRs and CRs completed:
   #2150: Constraint Network View: find constraint/variable nodes by key.
   #2157: Add window choices on pop-up menu for within Partial Plan.
   #2158: Need to greatly imporve load-times for sequences.
   #2159: Change option to Find By Key instead of Find Token By Key.
   #2160: Time to delete a sequence is way too long   
   #2161: Project menu goes away after deleting a sequence.
   #2167: Error creating a project.
   #2168: Other error behaviors creating project/sequence. Can't create a project.


16october03: Milestone 8
========================
Each sequence in the "Planning Sequence" menu now includes only the
"Sequence Steps" view, which is a histogram of the partial plan
data base size for each step.  The sequence step menu selections have
been removed.  Partial plan views for each step are now available
by clicking Mouse-Right on the desired step in the histogram
("SequenceStepsView").  The histogram steps have a "mouse over" pop-up 
showing the step number, the data base size, and the number of
transactions.

The Token Network View now is freshly layed out after applying a
Content Spec filter.

In all the partial plan views, Mouse-Right on the background offers
"Find Token by Key" which allows the user to enter a token's key and
have the view scroll to that token's location.

The Partial Plan Content Spec has been enhanced to handle token keys.
Click on either the "require" or "exclude" radio button, and then enter
the key value in the input slot.  To include more keys, click on "Add";
to remove keys from a previous "Apply Spec" set, click on "Remove".
The "require" or "exclude" selections override the "Predicate",
"Timeline", and "Time Interval" selections, with applied together.

Test use cases have been defined to replace the "planWorksTest" JFCUnit 
test which had become unusable.  A new unit test for the PlanWorks
data access layer is now in its place and can be run with 
"ant test".

The current PartialPlanWriter (PlanWorks/cpp/integration/europa/README)
requires a recent version of EUROPA.  The earliest known working
version is tagged with the PlanWorks milestone release tag PW_M_8.  
Note: Registering the PartialPlanWriter as a subscriber in
simplePlan.cc breaks EUROPA's make tests.  This is being worked
on.  

Please note that the current database model invalidates all old
data and will require a rebuilding of the database tables 
("ant planWorksDbInstall").

o  GNATS PRs and CRs completed:
   #2079: Users not telepathic-need to specify MySQL version.
   #2086: PlanWriter writes output files in wierd places.
   #2092: The filter of free token, etc from the content spec should 
          persist between window open and closes.
   #2107: Issues with display of Token Network and other windows.
   #2108: Changes in Token Network View.


23september03: Milestone 7
==========================
In the Timeline View, clicking Mouse-Right "Set Active Token" on a slot,
will now set the overloaded tokens as "secondary tokens", such that when
Mouse-Right "Snap to Active Token" is invoked in the background of the
Constraint Network View or the Token Network View, these secondary tokens
will be given secondary highlighting (turquoise).  The basic token will
have the primary highlighting color (light green).

The active node ("opened" or "closed" by Mouse-Left click) in the Constraint
Network View, is now positioned in the center of the view after layout.

The key values for tokens, constraints, variables, timelines, and slots now
appear in the appropriate node labels.

The planWorksTest ant target has been improved by adding the following menu
functionalities: "Project->Add Sequence ...", "Project->Delete Sequence ...",
and "Window->Tile Windows".

The PartialPlanWriter previously failed to create certain support
directories.  This is now fixed.

Completed several change requests and bug fixes.

o  GNATS PRs and CRs completed:
   #2056: No test data to add more than one sequence to the same project.
   #2089: Constraint Network View leaves dangling variable node after Content Spec.
   #2090: Need more info from the constraint network display about the actual objects.
   #2091: Graph-redrawing on CNet gets users lost.


18september03: Milestone 6
==========================
File "PlanWorks/GETTING_STARTED" has been added to assist new users.

The sequence directory chooser invoked by "Project->Create ..." and 
"Project->Add Sequence" now supports multiple selection of sequence
directories, by using Ctrl-Mouse-Left for the second and subsequent
selections.  Mouse-left is used for the first selection and Mouse-
Left-Double is used to open directories.  When selection is complete,
click on "OK".

The Temporal Extent View's time scale is now in a separate pane, so
that scrolling the token pane does not lose the time scale.  A
Mouse-Right selection "Set Time Scale Line" has been added.

The Temporal Extent View and  Timeline View are now redrawn after
Content Spec filtering is applied, so as to use screen space more
efficiently.

Each timeline now has a unique color, such that its tokens, in all
views, will have that same color.  In the Constraint Network View,
the variable and constraint nodes associated with a particular token 
will have that token's color.

The "Window" pull-down menu offers screen management with "Tile Windows"
and "Cascade".

Using the Content Specification, it is also possible to limit the set of 
valid tokens to, only free tokens, or only slotted tokens, as well as 
the first token on a slot ("Merge tokens").

Token focus in views has been implemented using Mouse-Right selections
on token or slot nodes to make them "active", and by Mouse-Right selections
on view backgrounds to "snap" the view to the active token.


o  GNATS PRs and CRs completed:
   #2044: Need a minimal getting started guide.
   #2048: In large plans, may lose the time scale with current approach.
   #2049: Project vertical line on clicks for Temporal Extent View.
   #2050: Synchronize focus among views.
   #2051: Need better window management - how about a tiling option?
   #2052: Need to handle redraw on content spec change to use space better.
   #2053: Post error message if trying to add sequence from other project.
   #2055: Bug creating project.
   #2057: Floating data left over filtering timeline view.
   #2058: Timeline color coding incorrect.  
   #2081: Must be able to filter free tokens in the content spec.
   #2082: Need to be able to filter merged Tokens.


05september03: Milestone 5
==========================
Milestone 5 adds the Constraint Network View. Because of its
complexity, initially only the token nodes are displayed.  They
are "opened" by mouse clicks which lay out the token's
variable nodes. Clicking on variable nodes "opens" them to show
or link to their nearest neighbors (constraints or tokens).
Similarly, clicking on constraint nodes "opens" their nearest 
neighbors.  Clicking on an "open" node (bold border), "closes"
that nodes nearest neighbor nodes/links, provided the link counts
are 1.  Then the node becomes "closed" and has an unbold border.

The Temporal Extent View layout has been improved.  The extent line
and associated arrows are displayed immediately below each predicate
node.  Downward arrows are start times, upward arrows are end times,
lefward arrows are -Infinity, and rightward arrows are +Infinity.

Free tokens are now presented in all views.  The automatic expansion
of the four view internal frame windows, now restricts the expansion 
to the size of the enclosing PlanWorks frame.  

The Content Specification processor now filters time intervals, as 
well as predicates and timelines.

Massive performance improvements have been made on database end, often by 
a factor of 4.

The first stage in Europa integration, the PartialPlanWriter is
included.  Instructions for its use are in
PlanWorks/cpp/integration/europa/README.

A new build target, hurtPlanWorks, has been added.  It finds all
directories containing planning sequences under the path pointed to by the
EUROPA_HOME environment variable, opens all available views for each
sequence, validates the views, then deletes the sequence from the
PlanWorks database.

PlanWorks now has a splash screen at startup.  The current image is not
permanent.

GNATS PRs fixed:
   #2011: Temporal extent view is wrong


24july03: Milestone 4 
=====================
Milestone 4 adds the Temporal Extent View.  It also automatically
expands the three view internal frame windows to display their
content, without scrolling.


17july03: Milestone 3 
=====================
Milestone 3 changes the backend data base content from XML accessed by
eXist using XPATH, to MySQL.  This results in a performance improvement 
of at least a factor of 3, and much simpler and quicker data
base queries by the Content Specification processor.  An XML to
MySQL convertor program has been added to convert planGen's XML output
to MySQL files.  The Token Network view has been added.  Project
management is now handled completely in MysQL, rather than using
Java "beans".  The Content Specification processor now filters only
by predicates and timelines.  It will later add time intervals.
o  PRs & CRs completed:
   #1841: Suggestion: group timelines for the same object
          Use alternating colors for grouping
   #1844: Suggestion: consider making interval endpoints immovable
   #1851: Closed View Windows are not restored by Partial Plan->seq->plan->view
   #1990: INSTALLATION: Problems with build.xml under linux


19june03: Milestone 2 
=====================
Milestone 2 integrates the Multiple Document Interface (MDI) for window
management, project management (creating, saving, opening and deleting),
the plan generator, and the Content Specification functionality for 
filtering partial plan rendering in the user selected views, which is 
currently restricted to the Timeline View.


27may03: Milestone 1 
=====================
Milestone 1 includes basic Timeline View, basic eXist XPATH DB
implementation, ant build/startup script, and basic JFCUnit test of 
Timeline View with major deficiencies.



DEVELOPING PLANWORKS
====================
Supports Emacs/XEmacs with JDE integrated development environment
http://jde.sunsite.dk/    # version 2.3.2

Additional Required environment varibles:
  o JDE_HOME - location of JDE 
    e.g. setenv JDE_HOME /home/wtaylor/pub/jde/jde-2.3.2
  o PLANWORKS_ROOT - directory pathname of this file
    e.g. setenv PLANWORKS_ROOT /home/wtaylor/PlanWorksProject/PlanWorks

used by PlanWorks/java/prj.el -- JDE configuration file

Other files used by  Emacs/XEmacs/JDE:
  PlanWorks/java/build-tags-file.csh
  PlanWorks/java/planWorks.TAGS


