mdb
1f0c38ddad
git-svn-id: https://samskivert.googlecode.com/svn/trunk@493 6335cc39-0255-0410-8fd6-9bcaacd3b74c
127 lines
5.1 KiB
Plaintext
127 lines
5.1 KiB
Plaintext
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 $
|