ViskitSoftwareDesignSummary.txt

This file will attempt to explain the inner workings of Viskit.

To build Viskit, from the command line, type "ant compile."  This process will
first generate XML binding source files from various Schema files located in the
"Schemas: directory.  The generated bindings are generated to specific packages
in the "src" directory of the Viskit build.  This is accomplished via JAXB.  XML
bindings help to interface java source with the XML representations of
EventGraph and Assembly files.

Next, the main Viskit source is compiled.  Viskit can now be launched by typing
"ant quick.run" on the command line.  How to use Viskit is explained in the
JavaHelp tutorial that can be accessed from Viskit once it's launched by
selecting the Help menu, or by launching the help menu via a command line call
to "ant help."

When Viskit is first launched, it creates a .viskit directory in the
${user.home}.  Here, configuration files are placed that can be modified from
Viskit by selecting File -> Settings.  Things such as what panels to expose, the
"look and feel" of the UI, size of the UI frame, what project space was last
opened, what files were recently opened, and other project history data are
recorded.  Various logging output files are also generated and placed there for
later reference should an error have occurred.  All of these can be accessed for
content review by running any of the "ant show.*" targets from the command line.

After the .viskit directory is populated, Viskit will popup a dialog to either
open an existing Viskit project, create a new one, or exit.  A default Viskit
project will be created in ${user.home}/MyViskitProjects/DefaultProject if the
user attempts to open an existing project, but then cancels.  If the user wants
to create a new project, the dialog will warn of a project with the same name
and give the user another chance to create a project with a different name.

A Viskit project consists of a set of directories and a project config. file:

AnalystReports      (main directory for reporting material)
  charts            (JFreeChart charts showing statistical data)
  images            (main folder for screenshots of all Assembly and EventGraph views)
    Assemblies
    EventGraphs
  statistics        (XML files of Simkit generated statistics)
  viskit.ico        (favicon for generated HTML reports)

Assemblies          (main folder for Assembly XML files)

EventGraphs         (main folder for EvevtGraph XML files)

build               (generated java source and byte code class files from EventGraph and Assembly XML files)
  classes
  src

lib                 (directory to hold project specific java based libraries)

viskitProject.xml   (project configuration XML file)

The most important feature of the viskitProject.xml file is the MD5 caching of
successfully validated and compiled EventGraph files.  This is to prevent
unnecessary recompilation of project materials once Viskit re-launches and opens
an existing project.  The MD5 hashes are recorded under the Cached element of
the viskitProject.xml file.  If a successfully cached and opened EG is modified
such that its XML is no longer valid, or doesn't compile, the cached line will
be removed from the project's cache element until the issue is resolved.  A new
MD5 hash will then be generated and recorded in the project's cache element.

MD5 caching is not performed on Assemblies.  Assy files are validated and
compiled each time the Assembly runner is launched.

If a Viskit project has specific dependencies, jar files can be placed in the
"lib" directory of the project and are automatically exposed on the classpath
which can be checked by selecting File -> Settings -> Additional classpath
entries.  Other dependencies can be placed on the classpath when not co-located
with an existing Viskit project by selecting those jars via the "+" button which