VIZTOOL: An extensible tool for visualizing Java classes
--------------------------------------------------------

As the catchy subtitle claims, viztool is used to generate visualizations
of collections of Java classes. These visualizations are intended to be
printed out and taped to the wall or set on the desk beside you or folded
into paper airplanes and sailed around the room. Thus viztool does not
include a sophisticated user interface for viewing these presentations
onscreen (use ghostscript for that), although you can actually display
them on the screen because the rendering is done via the Java 2D rendering
engine.

viztool was born from my repeated desire to be able to glance over all of
the myriad classes that come to be involved in any large project. I knew I
could go out and pay thousands of dollars for a single user license for
some object oriented design tool that would diagram my classes three ways
to Sunday, generate code, count my chickens and make toast on the side,
but I couldn't find a free, simple tool for generating basic class
diagrams.

Building viztool
----------------

Building viztool is very simple. First ensure that the necessary third
party jar files are available either in the lib/ directory or in the
system wide jar file location specified in build.xml. See lib/README for a
list of the necessary third party jar files and how to get them.

The library is built using ant, a modern build tool available from The
Jakarta Project. If you aren't already using ant for other projects, it
can be found here:

  http://jakarta.apache.org/ant/

Invoke ant with any of the following targets:

  all: builds the class files and javadoc documentation
  compile: builds only the class files (dist/classes)
  javadoc: builds only the javadoc documentation (dist/docs)
  dist: builds the distribution jar file (dist/viztool.jar)

Look at the build.xml file for configurable build parameters.

Using viztool
-------------

viztool is designed to be easily invoked from ant. Simply ensure that
viztool.jar and its associated dependent jar files are in the classpath of
the JVM that invokes ant and then add a task like the following to your
build.xml file:

  <target name="hierviz">
    <taskdef name="viztool" classname="com.samskivert.viztool.DriverTask"/>
    <viztool pkgroot="com.samskivert.viztool"
      classes="com.samskivert.viztool.*"
      visualizer="com.samskivert.viztool.hierarchy.HierarchyVisualizer">
      <classpath refid="classpath"/>
    </viztool>
  </target>

the parameters passed to the task are:

pkgroot: the base package name which will be used to strip common text
         from the front of fully qualified class names
classes: a regular expression matching the classes to be visualized
visualizer: the classname of the visualizer to use

the <viztool> element should contain a <classpath> element which defines the
classpath over which viztool will iterate, searching for classes that
match the specified pattern.

There is also an included shell script (bin/viztool). Add the classes that
you wish to visualize to your CLASSPATH environment variable and then
invoke the viztool script with the package prefix you wish to visualize.

For example:

% export CLASSPATH=<here>/foo.jar:<there>/bar.jar:<everywhere>/baz.jar
% ./bin/viztool --print com.whoever.mygreatpackage

Because the classes are actually resolved by the JVM when visualizing, all
classes that the visualized classes depend upon must also be loadable
(meaning included in the class path).

If you want to write your own script, take a look at the viztool script to
see what arguments to pass to the visualization driver class.

Distribution
------------

viztool is released under the GPL. The most recent version of the code is
available here:

  http://www.samskivert.com/code/viztool/

Contribution
------------

Contributions are welcome. Patches and suggestions can be sent to Michael
Bayne <mdb@samskivert.com>.

$Id: README 77 2005-03-13 22:33:46Z mdb $