Architecture Definition and Checking with Classycle

8. September 2010

Classycle [1] is a nice little utility for checking your internal Java program architecture. It can find cycles and can also check conformance with an architecture definition. You can check at the package level and at the class level. It’s compact, runs fast and it’s quite easy to use. Another neat fact is that it is open source and therefore doesn’t cost anything. At Catalysts we use it for defining the Taskmind [2] architecture and I recently used it to help define the architecture for a customer project. The customer requires keeping license costs to a minimum (or preferably zero) so commercial tools cannot really be considered.

Why Manage Your Internal Code Dependencies?

In short to promote reuse, modularization, maintainability etc and to avoid rigidity etc. See Robert C Martin’s paper for a great explanation [3].

Parts of Classycle

There are two main parts to Classycle: the Analyzer and the Dependency Checker.

Analyzer

The analyzer doesn’t require you to define any input parameters (except telling it where the code is). It runs through your code and outputs a report which contains details of package cycles, class cycles and automatically determined layers.

The Analyzer firstly uses “Tarjan’s strongly connected components algorithm” to condense the directed graph of components into groups of strongly connected components. Then it walks this graph to find cycles.

Here is some sample analyzer output:

<taskdef name="classycleReport" classname="classycle.ant.ReportTask"/> <target name="report"> <classycleReport reportFile="classycle.xml"> <fileset dir="."> <include name="classycle.jar"/> </fileset> </classycleReport> </target> </project>

Modifications by Me

Although the Analyzer generates a nice XML report, the existing Dependency Checker report just consists of plain text. Our customer requested that we produce a nicer looking dependency report. Looking at the documentation I saw that there was a ReportRenderer interface with one implementation class (DefaultReportRenderer). I assumed I could just create a different implementation which outputs HTML so I told the customer it would be no problem.

However when I started trying to implement it I saw that it was not as easy as injecting one different class. The plain text output was distributed across several classes and was actually impossible to replace (without code modification) because it came from toString() methods in internal classes which in turn used concrete classes not visible outside their package. This shows that the actual implementation of Classycle does not use dependency injection (everywhere). I then decided to import the Classycle source code into my Eclipse [5] workspace and start refactoring the code to make it possible to do what I originally wanted.

Unfortunately the refactoring was taking too long so (on the suggestion of a colleague) I went a different route. Instead of writing a replacement “renderer”, I wrote a class that takes the text output from the existing renderer and converts it to HTML in a separate step. Doing it this way required only minimal refactoring (mostly just a bit in the Dependency Checker Ant Task).

Things I Learned While Developing

How to write an Ant Task

I was surprised that it’s quite easy to write an Ant Task. You just need to extend org.apache.tools.ant.Task and implement the execute() method. You can define set methods for setting configuration parameters which can be passed from the Ant XML.

How to Debug an Ant Task

I needed a way to debug into the Classycle Ant Task and custom renderer. When you start an Ant Task from Eclipse you can’t debug into it because Ant runs as a separate program from Eclipse. One way to solve this is to start a headless Eclipse instance (eclipsec.exe) with the antRunner application and include the “wait for debugger” parameters:

set ECLIPSE_HOME=C:\eclipse\eclipse-jee-galileo-SR2-win32
set WORKSPACE=C:\workspaces\temp_dependency_checker_dev
set PROJECTS_BASE_DIR=C:\project
set PROJECT=my.project.name

%ECLIPSE_HOME%\eclipsec.exe -nosplash -data %WORKSPACE%
-application org.eclipse.ant.core.antRunner -buildfile
%PROJECTS_BASE_DIR%\%PROJECT%\classycle\dependencyCheck.xml
-vmargs -Xdebug -Xnoagent -Djava.compiler=NONE
-Dclasspath=%PROJECTS_BASE_DIR%\%PROJECT%\lib\classycle.jar;
%PROJECTS_BASE_DIR%\%PROJECT%\lib\classycle_extensions.jar
-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8086

Then back in your original Eclipse you start the remote debugger (connecting to the specified port) and it will stop at your breakpoints.

Shortcomings

One thing I would like to see in Classycle is some kind of X ‘uses only’ Y keyword. Availing of the ‘independentOf’ keyword, it is still possible to achieve the same effect but you first have to define the complement set of Y and then say X ‘independentOf’ Y-complement. Unfortunately this leads to poor readability of the definition file for a big code base.

Alternatives to Classycle

There are quite a few commercial alternatives to Classycle which generally provide nice graphical user interfaces (Classycle itself is command-line), IDE integration, some more powerful commands and fancier reports. They usually enable you to track metrics over time, so you can get an idea whether your architecture is improving or not. The alternatives include Structure101 [6], SonarJ [7], and Lattix [8].

Conclusion

Classycle seems to be the best free tool available at the moment for internal dependency checking and management. However, if you want 1) nicer reports 2) more convenient syntax 3) a graphical user interface you will probably need to look at a commercial tool.

Links

[1] Classycle http://classycle.sourceforge.net/
[2] Taskmind http://www.taskmind.net/en/
[3] Design Principles and Design Patterns by Robert C Martin http://www.objectmentor.com/resources/articles/Principles_and_Patterns.pdf
[4] Ant http://ant.apache.org/
[5] Eclipse http://www.eclipse.org/
[6] Structure101 http://www.headwaysoftware.com/products/structure101/index.php
[7] SonarJ http://www.hello2morrow.com/products/sonarj
[8] Lattix http://www.lattix.com/