README.txt for JAnalyze 1.0 - static code analysis for Java programs


JAnalyze is free software, coming with no warranty whatsoever. And no, it
is not fit for use in guiding spacecraft and airplanes or controlling
nuclear powerplants or other safety critical applications.


Files in this distribution:

  - README.txt   : This file
  - janalyze.bat : A windows shell script to start JAnalyze
  - janalyze.jar : A jar file containing all classes needed to run
		     JAnalyze
  - src.jar      : An archive with the entire source code of JAnalyze,
		      including JUnit tests and an ANT script
  - javadoc.jar  : An archive with javadoc documentation for the source
		      code


The primary focus of JAnalyze is to help understand and analyze large Java
systems. The focus is not on amassing heaps of numbers, and the focus is
not to help beginners avoid simple coding mistakes. Therefore, JAnalyze
does not read in source code but rather byte code (".class" files). It also
provides only an interactive graphical user interface; a command line
interface for batch operation is useful and will be added in a future
version, it is just not there yet, and other features have a higher
priority.

This document gives an introduction of how to use JAnalyze.


Control Center
--------------

The program can be started calling "janalyze.bat" from the directory where this
batch file is. After the application is started, it shows a window with a
single inner window, the "control center". This window is where you can
control what project JAnalyze currently works on, and it can not be closed.

In the control center, you can define a *project*, which is JAnalyze's term
for a collection of classes you want to take a look at. In order to define
a project, you need to define the classpath for the application and enter
one or more root classes.

The class path can contain directories and JAR/ZIP files. Since JAnalyze
operates on byte code rather than source code, you can (but do not have to)
enter libraries that your project uses. If you add them to the classpath,
they will be analyzed as well, if you do not, they will simply be
ignored. Caution: You must specify where your class files are, JAnalyze
does not care about .java files!

Root classes are where JAnalyze starts its analysis. It starts at the root
classes and then analyzes every other class that is used by the root
classes, and all other classes that these classes use etc. Classes with a
main method or servlets are typical candidates for root classes.

You can load or save project definitions; "*.jan" is the suggested
extension for such project definition files.  You can also apply any
changes you have made, even if you do not choose to save them. If you do
that, JAnalyze starts reading in and analyzing the classes. You can watch
the progress in the lower half of the control center.  When JAnalyze is
finished reading in a project, a message appears there saying so.


Views
-----

After JAnalyze has read all project classes, you can start the actual
analysis; the main menu item "View" contains the options for this. Each of
these options creates a new inner window so that you can have several
analysis windows of the same kind at the same time.

"Tree View" opens a hierarchical tree view of the project. Packages are
marked with a blue bullet, classes are green and methods are red. At each
of these levels, there is also the information of fan-in and fan-out,
showing the dependency structure of the project. Fan-In of an entity means
all entities that depend on it, fan-out means all entities that it depends
on. While fan-out is directly visible in the source code of a
class/package/method, fan-in requires the analysis of the entire project
(which JAnalyze does for you).

"Package, class and method metrics" open a table with a list of all
packages/classes/methods in the project and some metrics (numbers
calculated from the project structure). These metrics can provide some
insight into the design and structure, and they can be helpful for
understanding things or as pointers to surprising places where it might be
a good idea to take a look at the source code, but they should *never* be
used to blindly assess the quality of anything - that just does not work.

At all these levels, there are the metrics "# fan-in" and "# fan-out" which
are defined as the number of packages/ classes/methods in the fan-in /
fan-out of of the entity in view.

"Number of classes in package" and "Number of methods in class" are just
what their names say they are.

"Pseudo-cyclometric complexity" is an approximation to McCabe's
cyclometric, based on what is straightforward to reconstruct from byte
code.


Export
------

Export functionality uses the Apache Velocity library. This library uses
templates with an embedded script language; the Java application that calls
the library can register Java objects that are then available from this
script language.

JAnalyze parses the "templates" directory at startup time and interprets
every file ending with ".vm" in this directory as an export option and adds
it to the "Export" menu. Additionally there is an entry allowing to choose
an arbitrary template at run time. When you choose one of the export entries,
a file chooser dialog pops up asking you to enter a file name for the
generated output file.

JAnalyze registers several objects before calling the templates:

$now            a java.util.Date instance with the current time
$pool           an instance of janalyze.project.JClassPoolData (see javadoc). This
                    object allows access to the entire structural information of
                    the project and has many convenience methods
$project        an instance of janalyze.guimdi.controlcenter.Project (see javadoc).
                    This object allows access to the project definition.
$packageMetrics convenience collection containing all package metric definitions
                    (instances of janalyze.metric.JPackageMetric; see javadoc)
$classMetrics   convenience collection containing all class metric definitions
                    (instances of janalyze.metric.JClassMetric; see javadoc)
$methodMetrics  convenience collection containing all method metric definitions
                    (instances of janalyze.metric.JMethodMetric; see javadoc)

For details on writing or modifying Velocity templates, see the Velocity
documentation. The templates that are provided with JAnalyze are a good starting
point for understanding how Velocity works. All templates are read in at run time,
so you can test changes to a template without restarting JAnalyze.
