Classycle logo

1.1 Analyser

Classycle's Analyser can be used as a command-line tool and as an Ant Task.

1.1.1 Command Line Tool

Analyser is called from the command line as follows:
java -jar classycle.jar [-raw] [-cycles|-strong] [-packagesOnly]\
                        [-excludingClasses=<pattern1>[,<pattern2>,...]] \
                        [-reflectionPattern=[<pattern1>,<pattern2>,...]] \
                        [-xmlFile=<file>] [-csvFile=<file>] \ 
                        [-title=<title>] \
                        <class files, zip/jar/war/ear files, or folders>
The argument is a list of sources for class files to be analyzed:
  • Particular .class file
  • zip/jar/war/ear files: All class files in such a compressed file
  • Folder: All class files in the folder (including all subfolders) and all class files in zip/jar/war/ear files of the folder

The options have the following meaning:

The complete digraph will be printed onto the console.
All cycles and their containing classes are printed onto the console.
Like -cycles but also the strong components with only one member are printed onto the console. Thus all classes are printed.
Only package dependencies are calculated.
Inner class vertices will be merged with their outer classes.
Comma-separated list of one or more wild-card patterns for fully-qualified class names of classes which are included in the graph. Only '*' is interpreted as wild-card character.
Comma-separated list of one or more wild-card patterns for fully-qualified class names of classes which are excluded from the graph. Only '*' is interpreted as wild-card character.
Comma-separated list of zero or more wild-card patterns for fully-qualified class names which are referred in the class file by plain string constants. Only '*' is interpreted as wild-card character.

This allows e.g. that a class with the following line of code has a reference to java.lang.Thread:

Class clazz = Thread.class;
The following code has the same effect:
String className = "java.lang.Thread";
If no pattern is defined all strings which are valid class names (like hello, would be treated like class references.
Creates the specified file with an XML report.
Creates the specified comma-separated-value (CSV) file containing a table with all classes but no dependencies.
Value of the title element of the XML report. If the title is not specified the first argument of the list of class files will be used.
Without any options only a brief summary is printed onto the console.

The XML report refers to the XSL transformation reportXMLtoHTML.xsl. Modern Web browser are able to render the XML report with the help of this XSL transformation. Otherwise an XSLT processor (like xalan) is needed to create an HTML document from the XML report. In any case the folder images is needed in the same directory as the report (and the XSL file).

1.1.2 Ant Task

I wrote an Ant Task based on the Ant Task written by Boris Gruschko (see Patch 977610: Ant task for classycle). Here is a simple build file showing its usage:

<?xml version="1.0"?>
<project name="Classycle Ant Task Example" default="report" basedir=".">
  <taskdef name="classycleReport" classname="classycle.ant.ReportTask"/>

  <target name="report">
    <classycleReport reportFile="classycle.xml">
      <fileset dir=".">
        <include name="classycle.jar"/>

The source of class files can be specified by filesets and zipfilesets. For the attributes and their meaning see the API documentation of ReportTask. Running this example build file on the console yields

Buildfile: exampleBuild.xml

[classycleReport] ============= Classycle V1.0 =============
[classycleReport] ========== by Franz-Josef Elmer ==========
[classycleReport] read class files and create class graph ... done after ...
[classycleReport] condense class graph ... done after ...
[classycleReport] calculate class layer indices ... done after ...
[classycleReport] create package graph ... done after ...
[classycleReport] condense package graph ... done after ...
[classycleReport] calculate package layer indices ... done after ...

Total time: 1 second

and a file classycle.xml with the XML report of the analysis of classycle.jar.

To run with Ant 1.6 type:

ant -lib classycle.jar -f <build file>  <target> 

For earlier Ant versions the option -lib does not work and you must copy classycle.jar into the folder lib of the home directory of your Ant installation.

The Ant task has been tested with Ant 1.5.3 and 1.6.1.