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.
Thus, viztool aims to provide an extensible framework for generating
visualizations of collections of classes. This initial release generates
inheritance diagrams organized by package, with information on interfaces
implemented and (non-anonymous) inner classes as well. It is somewhat
modular, although not as thoroughly as I'd like because, like all
projects, it was completed in haste and with an eagerness to see the final
product that isn't entirely conducive to elaborate design. There are also
various enhancements I'd like to make to the inheritance visualization.
Excuses aside, the foundation is laid and adding other visualizations
should be a reasonably straightforward process after having had a look at
the existing code. So if you've got some handy visualization in mind, take
a crack at it, or at least email me with the idea so that I can put it on
a list and someone else might do it for you.
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.waywardgeeks.org/code/viztool/
Contribution
------------
Contributions are welcome. Control of the CVS repository is presently in
the hands of mdb@samskivert.com, who should be emailed about submissions.
Facilities for management of major contributions by external parties
(ie. publicly accessible CVS server) will be provided if circumstances
dictate.
Contact Information
-------------------
The person primarily responsible for viztool is Michael Bayne and can be
contacted at <mdb@samskivert.com>.
$Id: README,v 1.3 2001/12/03 08:34:05 mdb Exp $
mdb
fcd800ce02