A metrics tree map visualises the structure of the code by rendering the hierarchical package (namespace) structure as nested rectangles, with parent packages encompassing child packages. The actual display is taken up by the leaves in this structure, the classes. Have a look at the following tree map which shows the JRuby code base, without worrying too much about the “metrics” part yet.

At the top right I have highlighted the org.jruby.compiler package. The tree map shows that this package contains a few classes, such as ASTCompiler and ASTInspector, as well as three subpackages, namely impl, ir, and util, with util for example containing a class called HandleFactory, visible on the far right. (Visible in the full-size version.) In the following I explain how the tree maps visualise metrics, and I will explain how to create such maps from Java source code. As usual, adapting this other programming languages is relatively easy.

Showing metrics in the tree map

From the JRuby example above it is clear that tree maps can visualise two metrics by using the size and the colour of the rectangles. In the example the size of the rectangle represents the number of lines in the corresponding file (the actual length of the file, not the sum of the lines of code in all the methods) while the colour shows the sum of the cyclomatic complexity of all the methods in the class; the redder the class, the higher the complexity.

This map allows easy identification of large and complex classes, and usually file size and complexity are correlated, meaning that larger rectangles appear in a darker shade of red. The left third of the JRuby tree map follows this pattern almost perfectly. However, the tree map also highlights an exception to this pattern: the IANA class in the org.jruby.ext.socket package. This class is large but has a very low complexity for a class if its size, something that is worth an investigation.

It should be obvious that other size metrics, such as method count or length, could be mapped to the rectangle size, while metrics such as class fan-out or data abstraction coupling could be mapped to the colour. Going further, while it is intuitive to show a size-based metric as the size, it can be worthwhile to map other metrics to the size. For example, a tree map showing complexity via the size and fan-out as colour makes it obvious which complex classes have high fan-out and which ones have not. This can be useful to identify which (overly) complex classes can be refactored more easily. In a class that has lower fan-out the complexity is more “self-contained”, likely allowing for one or more easy Extract Class refactorings.

Going beyond these examples, it is also possible to map non-metric information onto the colour, for example the name of the dominant committer of a file. In such a case each committer would be mapped to an individual colour, and rectangles could be shaded grey if no single committer accounted for more than a certain percentage of commits. Such a view would show whether a development team has bought into collective code ownership, or whether developers have carved off individual packages for themselves. More ideas, and other visualisations here.

Using Checkstyle to get metrics

Checkstyle is meant to report on violations of guidelines, usually if a numeric threshold is exceeded. (I’ve shown how this data can be visualised in a previous article.) If all thresholds are set to zero Checkstyle considers everything a violation and reports all metrics. The following file shows the configuration used for this article.

<module name="Checker">
  <property name="severity" value="warning"/>
  <module name="TreeWalker">
    <module name="FileContentsHolder"/>
    <module name="FileLength">
      <property name="max" value="0"/>
    </module>
    <module name="MethodLength">
      <property name="max" value="0"/>
    </module>
    <module name="ClassDataAbstractionCoupling">
      <property name="max" value="0"/>
    </module>
    <module name="ClassFanOutComplexity">
      <property name="max" value="0"/>
    </module>
    <module name="CyclomaticComplexity">
      <property name="max" value="0"/>
    </module>
  </module>
</module>

With this file saved as “metrics.xml” Checkstyle can be invoked as follows to create an XML file containing all metrics we are interested in.

java -jar checkstyle-all-4.1.jar -c metrics.xml -f xml -o checkstyle_out.xml -r <source_dir>

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.1">
<file name="jruby-1.4.1/src/org/jruby/anno/AnnotationBinder.java">
<error line="1" severity="warning" message="File length is 487 lines (max allowed is 0)." source="com.puppycrawl.tools.checkstyle.checks.sizes.FileLengthCheck"/>
<error line="31" column="1" severity="warning" message="Class Data Abstraction Coupling is 1 (max allowed is 0) classes [AnnotationBindingProcessor]." source="com.puppycrawl.tools.checkstyle.checks.metrics.ClassDataAbstractionCouplingCheck"/>
<error line="31" column="1" severity="warning" message="Class Fan-Out Complexity is 5 (max allowed is 0)." source="com.puppycrawl.tools.checkstyle.checks.metrics.ClassFanOutComplexityCheck"/>
<error line="36" column="5" severity="warning" message="Cyclomatic Complexity is 1 (max allowed is 0)." source="com.puppycrawl.tools.checkstyle.checks.metrics.CyclomaticComplexityCheck"/>
<error line="36" column="5" severity="warning" message="Method length is 3 lines (max allowed is 0)." source="com.puppycrawl.tools.checkstyle.checks.sizes.MethodLengthCheck"/>
...

For languages other than Java other tools can be used to create a similar output file. The format does not need to be exactly the same (more later).

Drawing tree maps with InfoVis

I’ve been using the InfoVis Toolkit for years and while development on it has stagnated it just works; at least as long as a Java 5 runtime is available, which, unfortunately, is not the case on Mac OS X Snow Leopard. I’m open to suggestions of better/newer tools…

InfoVis is an interactive Java application that has a decent user interface to map various fields of the input file onto different aspects of the tree map, size and colour being two obvious ones. At this point it is probably worth mentioning that I generally also “sort” the tree map by whatever metric I have mapped to the size. The screenshot on the right shows the settings I used for the JRuby tree map above, and in case you wonder about the abbreviations for the metrics, FLENGTH is obviously file length, and WMCcc stands for Weighted Method Count (cyclomatic complexity).

Data conversion

The remaining piece of the puzzle is the transformation of the Checkstyle output into a format that InfoVis can interpret. Luckily, the input file format for InfoVis, named TM3, is very simple. The following excerpt shows data for the first few classes of the JRuby code base.

FLENGTH	CDAC	CFOC	MCOUNT	WMCloc	WMCcc
INTEGER	INTEGER	INTEGER	INTEGER	INTEGER	INTEGER
487	6	16	15	422	87		org	jruby	anno	AnnotationBinder
21	0	1	0	0	0		org	jruby	anno	Coercion
14	0	0	0	0	0		org	jruby	anno	CoercionType
5	0	0	0	0	0		org	jruby	anno	FrameField
69	6	9	1	54	11		org	jruby	anno	InvokerGenerator
136	1	3	4	93	26		org	jruby	anno	JavaMethodDescriptor
20	0	0	0	0	0		org	jruby	anno	JRubyClass

The first line contains the names of the metrics, the second line their data types. Both are tab separated. The remaining lines contain the metrics for each of the classes followed by the tree structure, with all package nodes flattened out and separated by tabs as well. Sometimes non-XML formats are so refreshingly easy to work with.

A small Ruby script, which I have attached further down can be used to convert Checkstyle’s XML output into the TM3 format, using a command like this:

ruby checkstyle2tm3.rb checkstyle_out.xml <source_dir> > treemap.tm3

Currently, the script has the path separator hard-coded. If you intend to run this script on a Windows machine you have to change the path separator constant in line 6 manually.

This Zip archive contains the Ruby script used to convert Checkstyle XML output format to the InfoVis TM3 file format. Remember that you might have to change the path separator.

Returning to classes and packages, the following matrix shows a view of some of the core classes of the Spring framework:

In this typical package DSM the packages are listed on both axes. If a package has dependencies on another package, the number of dependencies is listed at the intersection. The package that has the dependency is on the top, the package that it depends on is on the left. In the example above the matrix shows that there are seven dependencies from the beans.propertyeditors package to the core.io package.

The first, and most obvious, issue that can be spotted in a DSM is a cyclical dependency. Most tools (more on those at the end of the post) try to arrange the matrix such that all dependencies are shown in the lower left triangle. A cyclical dependency makes this impossible and one “half” of the dependency will be shown in the upper right triangle.

In the following matrix, which shows a package view of the Jetty server, we can see that jetty.webapp has six dependencies on jetty.handler but the latter also has a single dependency on the former.

Another design concern is that of cohesion and coupling, very well explained here. Applying this to a package level and DSM it is good to see dependency numbers arranged in squares, showing cohesion between related packages, but rows or columns filled with numbers are often a concern. A row filled with numbers signifies a package that many other packages depend on. This can be acceptable, as in the util package in the Spring matrix above, but often it is a sign of a lack of cohesion. Conversely, a column filled with numbers represents a package that depends on many other packages, which is usually a sign of bad coupling and the possible presence of god classes and feature envy.

These patterns become even more apparent when looking at larger systems. The following matrix is a zoomed out version showing most of the Spring framework.

There is a good cohesion, shown in pink, in many of the subpackages, but there are also some classes that invite a large number of dependencies, shown in blue, as well as a couple of classes that have unfocussed dependencies, shown in green.

At this point I should probably mention that I think that the Spring framework is fairly well designed, and that I’ve seen quite different matrices in the wild.

I hope I have convinced you that DSMs are worth a look, and luckily there is now widespread support for DSMs, in IDEs, e.g. IntelliJ, and in tools, e.g. Structure 101, Lattix, .NET Reflector. The screenshots in this post were created with Structure 101 for Java.

The reason why developers need an up-to-date build status is a common, and good, practice: new check-ins are only allowed when the build is known to be good. If it is broken chances are that someone is trying to fix it and dumping a whole new set of changes onto them would undoubtedly make that task harder. Similarly, when the server is building nobody knows for sure whether the build will succeed, and checking in changes would make fixing the build harder, should it fail.

To recap: the build must be good for a developer to be able to check in. On one of our projects this was becoming a rare occurrence, though. In fairness, the build performed fairly comprehensive checks in a complex integration environment, involving an ESB and an SSO solution. The team had already relegated some long-running tests to a different build stage, and they had split the short build, ie. the build that determines whether check ins are allowed, into five parallel builds, bringing build time down from over 45 to under ten minutes. Still, developers often found themselves waiting in a queue, maintained with post-its on a wall, for a chance to check in their changes. Not only that but everybody felt the situation was getting worse, that the build was broken more often. This was obviously a huge waste and I was keen to make it visible to management using a visualisation.

Buildlines visualisation

After some experimentation I decided on a variation of spark lines for the build status. Each of the builds gets its own line and the colour shows the status of the build at any given point in time, green for good, red for broken, and blue for building. I blanked out the weekends and stretched the time during the days so that only the hours between 8am and 7pm are visible. The resulting visualisation looked like this: (Click through for the full-size version.)

The zoomed out version clearly shows that matters were getting worse. The first two weeks in this diagram only show a few broken builds that, with the exception of one episode on build number 4 on Aug 11/12, get fixed relatively quickly. Looking at the last week and a half the picture changes quite dramatically:

On Monday, Sep 7, build 1 is broken for a while, which can happen. Later in the day build 2 breaks and is only fixed early on Tuesday. Again, this alone would not concern me, and while it is generally not such a great idea to leave a broken build behind, sometimes it is important to go home and get some rest.

At this point I should probably clarify that for a developer to be able to check in all the builds in this diagram need to be green. Each test in each build of this stage is significant. Long running, brittle tests, which include end-to-end integration tests with a mainframe system, have been moved to a different build stage and are treated separately.

A real reason for concern is that that around noon on Sep 8, all builds break at the same time. This is unlikely to be the result of a code change, because for a single change to break all builds it would have had to affect at least one test in each of the builds. Possible but not likely. A more reasonable explanation for this failure is a problem with the environment, maybe a database that is not responding or an SSO server that cannot authenticate the test users any longer. Similar problems can be seen Sep 14 during the morning, and Sep 15 in the afternoon. They are not completely new, either, as looking at Aug 28 reveals.

Environment problems like these can be extremely frustrating for a development team because a build that is broken not because of a code change but because of a problem with the environment leaves the developers in an awkward position. They can either wait until the environment is fixed, but that often relies on a separate team that may have different priorities, or they can continue to check in based on the assumption that the build isn’t really broken. The latter is, of course, playing with fire as the team now effectively works without continuous integration.

Visualisations such as this one can help management get clarity on environment problems, and hopefully support a case for improving the build environment.

The buildines script

Unlike the visualisations I wrote about on this blog so far, this time I needed to write a bit more code as I could not find a tool to draw the spark lines for me. The data acquisition step was easy, though, because the team was using the Cruise continuous integration server, which allowed me to get information about past builds through a web-based API. I used the cURL command, which, by the way, is available for Windows, too.

curl -o Shortbuild1.csv "http://servername:8153/cruise/properties/search?pipelineName=WebFrontEnd-Dev&stageName=Shortbuild&jobName=Shortbuild1&limitCount=1000"
curl -o Shortbuild2.csv "http://servername:8153/cruise/properties/search?pipelineName=WebFrontEnd-Dev&stageName=Shortbuild&jobName=Shortbuild2&limitCount=1000"
...

Normally I’m advocating to split the data processing stage from the actual visualisation but in this case, because I was going to write the visualisation from scratch and the data coming from Cruise was in a pretty good format already, I decided to put everything into a single script. For that I chose Ruby and RMagick. The latter can be a pain to set up but there are installers for Windows, on the Mac it can be installed using MacPorts, and presumably the Linux package management systems include it, too.

The script is available from this Bitbucket repository. It is relatively straight-forward and I am not going to examine it in great detail in this post. What is noteworthy is that, internally, the script shows a separation of concerns, with one class reading the Cruise files, a second class scaling and drawing the lines and labels, and a main class that holds everything together. If you were to adapt this to a different continuous integration server it should be possible to achieve this by simply writing a different DataFile class.

To run the script simply pass the list of build status files as command line parameters to it:

ruby buildlines.rb Shortbuild*.csv

The output will be written into a file named buildlines.png in the working directory. If you prefer a different format you can change the extension of the filename in the script, and RMagick, provided it supports the format, will magically write the corresponding format.

The visualisation script can be downloaded from Bitbucket. Simply select one of the zipped versions of the “tip” snapshot.

Most of the Moose tools now use the MSE file format as an interchange format. By the way, if you are interested in writing your own visualisations or analysis tools it is probably worthwhile looking at MSE, reading this format is so much more convenient than parsing source code.

In Java it was always relatively easy to create MSE files. Among many other things, iPlasma can read Java source code and export to MSE. That said, iPlasma has so many interesting features itself that oftentimes no export to an external tool is necessary.

For C# the story was different and for one reason or another no tool existed that could create MSE files for C#. This has changed now. As a student project at the University of Lugano such a tool was written and, thanks to Michele Lanza, then donated for general use. I’ve made a few improvements and put the code into this Bitbucket repository.

The diagram above only shows one of the content services, which for the sake of this article is a service that provides contact details for a person.

Based on conversations with the project sponsors I began to suspect that at least the introduction of the ESB was a case of RDD, ie. Resume-Driven Development, development in which key choices are made with only one question in mind: how good does it look on my CV? Talking to the developers I learned that the ESB had introduced “nothing but pain.” But how could something as simple as the architecture in the above diagram cause such pain to the developers? Was this really another case of architect’s dream, developer’s nightmare?

Often a picture says more than a thousand words, but at the same time traditional architecture diagrams simply do not provide enough information. (I’ve argued this before, here and here for example.) The answer to my questions, and the anxious project sponsors’ question whether the project would deliver on time, lay in a different picture.

The picture should not only show the layering of the system in more detail than the architecture diagram but it should also visualise the complexity introduced by the ESB. It’s often possible to produce more detailed diagrams automatically from source code, configuration, or runtime inspection but in this case I couldn’t find a way to do that, which is which I drew the following:

In the centre column this diagram shows the layers involved, from the Struts action that needs to look up details by an ID down to the back-end that provides a “RESTful” service to retrieve the details. The top box contains the front-end layers while the box in the middle represents the ESB. The layers labelled in italics are frameworks or infrastructure software, the rest is project-specific code.

Key to this diagram are obviously the coloured representations of data travelling up and down the stack. Primitive types are grey, Java objects are purple circles, XML documents are shown as turquoise hexagons, and HTTP messages as green blobs. Mule messages, which are Java objects, are shown in dark purple. If one representation is wrapped in another it’s displayed inside the wrapper.

The diagram highlights that it’s a simple piece of data that travels all the way down the stack (actually further until it hits a relational database at some point) and, equally, that the data needed by the action is available in the right form from the service. All that the intermediate layers are doing is wrapping and unwrapping the data in various ways. In fact, out of the four layers of project-specific code three layers do nothing but wrapping. No wonder the developers felt some pain.

As a side note: the diagram also makes it obvious that the wrapping is asymmetric between the WsToRestHandler and the RestServiceWrapperImpl, which makes the point of this layer boundary even more questionable.

This diagram made people more interested in the cost of what had just been a simple, innocuous line in the architecture diagram; which was the point of the exercise. So, what would this diagram look like without the ESB? Easy:

Apart for the obvious simplicity the diagram highlights that every layer has a purpose and there is only one wrapping, which is not undone either. Would it surprise you if I told you that the project went live without the ESB?

Footnotes

1) This article is by no means implying that any of the mentioned technologies are useless or harmful. Their use was harmful in this case.

2) The pattern of wrapping and unwrapping the same data through multiple layers is not new, it was also quite common in early 3-tier architectures. (In fact, some people called their architectures n-tier; I guess to show that the number of tiers was somewhat arbitrary but large.) We had a term to describe this pattern: the wormhole pattern.

3) This project is not an isolated incident of a Wormhole ESB. I have personally seen several in the past years.

Now, as a developer, how do you help managers and business people understand the internal quality of code? They generally want a bit more than “it’s horrible” before they prioritise cleaning up the code over implementing new features that directly deliver business value. Or even: how do you figure out for yourself how bad some code actually is in relation to some other code? These were questions that Chris Brown, Darren Hobbs, and myself were asking ourselves a couple of years ago.

The answer came in the form of a simple bar chart, arguably not the most sophisticated visualisation but a very effective one. And our colleague Ross Pettit had the perfect name for it: The Toxicity Chart. Read on to see what it is and how it’s created.

As usual, let’s start with an example. What follows is the toxicity chart for a version of the Hibernate framework.

In a toxicity chart each bar represents a class and the height of the bar shows the toxicity score for that class. The score is based on several metrics (more on that below) and the higher the score the more toxic the class. The individual components of the score are coloured. For example, the contribution of the method length metric to the overall score is shown in orange. This makes it possible to see at a glance not only how toxic a codebase is but also how the problems are distributed. If there is a lot of purple and orange in the chart, this indicates long and complex methods, which means that the code is probably hard to test on a unit level. Lastly, classes that score zero points are left off the chart.

The calculation of the toxicity score is based on metrics and thresholds. For example, the method length metric has a threshold of 30. If a class contains a method that is longer it gets points proportional to the length of the method in relation to the threshold, e.g. a method with 45 lines of code would get 1.5 points because its length is 1.5 times the threshold. The score for all elements is added up. So, if a class comprises two methods, one that is 45 lines and another that is 60 lines long, the method length component of the score for the class will be 3.5 points. This means that elements are not just classified as toxic but the score reflects how toxic the element is.

The following table shows the metrics that make up the toxicity score and the corresponding base threshold on which the multipliers are based.

At this point you might wonder where the selection of metrics and thresholds comes from. Well, we made them up. When we designed the toxicity chart we made a call on what constitutes “toxic” as opposed to just bad. Of course, staying with the method length metric, we normally wouldn’t want to see a 15-line method but that might be disputed. However, we hope that nobody thinks that a 30-line method is acceptable. And in case you’re really uncomfortable with the thresholds, you can obviously change them to build your own toxicity score. We do suggest, though, that you try the values presented here first.

Like many visualisations the creation of the toxicity chart falls into two steps: data acquisition and rendering.

Step 1: For Java projects Checkstyle is the easiest way to get the metrics. The score table above easily translates into a Checkstyle configuration file, which, by the way, is included in the Zip archive attached to this page. Assuming this file is named “metrics.xml” Checkstyle can be invoked like this:

java -jar checkstyle.jar -c metrics.xml -r <source_dir> -f xml -o toxicity.xml

Afterwards, the file “toxicity.xml” contains a list of all components for the toxicity score in an XML format.

Similar tools for other languages should be able to create similar output. It is not a huge problem if the output is somewhat different as it’s always possible to change step 2 to handle different input formats.

Step 2: What is required next is to read the data from XML, aggregate it on a per-class level, and then render the bar chart. Microsoft Excel is good at the latter two but it needs a bit of help to read the XML file. This help comes in the form of a small piece of VBA code. The attached Excel workbook contains a sheet to load the data, an “Open XML” button backed by said VBA code, a pivot table to do the aggregation, and the chart based on the table. So, step 2, really is to open the Excel workbook and load the XML file. That’s all.

Now, if you know me you know that I’ve been working with Macs for a very long time. So, naturally, I’d like to use Excel on the Mac but, alas, in its current version it does not support VBA anymore. So, unfortunately, it’s VMWare Fusion for this one.

This Zip archive contains everything needed to create a toxicity chart for Java. The spreadsheet can be adapted to read input file formats created by tools for different languages; just edit the VBA behind the “Data” sheet.

Call graphs show how methods call each other, which can be useful for a variety of reasons. The example I use here is the graph rooted in a unit test suite, and in this case the graph gives an understanding of how localised the unit tests are, how much they are real unit tests or how close they are to mini-integration tests. In an ideal case the test method should call the method under test and nothing else. However, even with mock objects that’s not always practical. And if, like myself, you fall into the classicist camp of unit testers, as described by Martin Fowler in Mocks aren’t Stubs, you might actually not be too fussed about a few objects being involved in a single test. In either case, looking at the call graph shows you exactly which methods are covered by which unit tests.

There are several ways to generate calls graphs and I’m opting for dynamic analysis, which simply records the call graph while the code is being executed. A good theoretical reason is that dynamic analysis can handle polymorphism but a more practical reason is that it’s actually really easy to do dynamic analysis; provided you use the right tools. The approach I describe in this article uses Eclipse AJDT to run the unit tests with a simple Java aspect that records the call graph and writes it out into a format that can be rendered more or less directly with Dot. Of course, this technique is not limited to creating graphs for unit test; it only depends on weaving an AspectJ aspect into a Java application.

Let’s start with the result. The following diagram shows the call graph for a few simple unit tests in the test suite for the CruiseControl dashboard. The tests methods are in the leftmost column and method invocations occur from left to right. It’s clearly visible that the tests are quite localised.

The next example shows a section that’s a bit more intertwined. Some tests exercise the same method, some tests call more than one method, and some methods are called indirectly through different paths. All in all pretty reasonable, though.

Now, I don’t want to showcase only the good parts. There are also sections in the graph that show how some of the test and dependencies are, well, a bit messy. In fairness, though, this is partly caused by some domain objets that are used across multiple tests.

How hard can it be to create these graphs? Not very, as it turns out.

Step 1 is to create an aspect that intercepts all interesting method calls, which normally means calls to methods that are part of the project. It’s also possible, though, to include calls to libraries and frameworks. Depending on your experience with AspectJ this is as simple as follows:

package com.example.callgraph;
 
public aspect CallInterceptor
{
    pointcut allInterestingMethods():
        !within(CallInterceptor) && !within(CallLogger) &&
          execution(public * com.example..*(..));
 
    before() : allInterestingMethods() {
        CallLogger.INSTANCE.pushMethod(thisJoinPointStaticPart.getSignature());
        CallLogger.INSTANCE.logCall();
    }
 
    after() : allInterestingMethods() {
        CallLogger.INSTANCE.popMethod();
    }
 
}

The first part of the aspect is the definition of the pointcut: it matches all public methods in “com.example” and sub-packages but excludes calls to the two classes that form part of the call graph logger itself.

The before advice, which is run before each method that matches the pointcut, places the signature of the current method on a stack maintained by the graph logger class. With the current method signature as the topmost element and the one that called it as the second from the top, the advice asks the logger to log the corresponding call. The after advice simply pops the topmost call from the stack.

This is almost all the excitement. The implementation of CallLogger deals with maintaining the stack and writing out the call in the format required by Dot. The complete implementation with some comments follows below.

package com.example.callgraph;
 
import java.io.BufferedWriter;
import java.io.FileWriter;
import java.io.IOException;
import java.io.Writer;
import java.util.Stack;
import java.util.HashSet;
import java.util.Set;
 
import org.aspectj.lang.Signature;
 
public class CallLogger
{
    public static CallLogger INSTANCE = new CallLogger();

An instance is made available as a public singleton. The main reason for using a singleton, rather than creating an instance in the aspect, is that if coherent logging is required across multiple projects in Eclipse it’s easiest to add a copy of the aspect to each project and have all aspects use the same logger instance.

    private Stack<String> callStack = new Stack<String>();
    private Set<String> callLog = new HashSet<String>();
    private Writer writer;

The fields hold the actual stack of method names, a set that contains all calls that have been logged already, and a writer to which the actual output is written. The set is a simple optimisation to prevent the same call from being written over and over again.

     public CallLogger() {
        try {
            writer = new BufferedWriter(new FileWriter("calls.txt"));
        } catch (IOException e) {
            throw new RuntimeException("Cannot open 'calls.txt' for writing.", e);
        }
    }
 
    public void pushMethod(Signature s) {
        String type = s.getDeclaringType().getName();
        String method = type.substring(type.lastIndexOf('.') + 1) + "." + s.getName();
        callStack.push(method);
    }

If anyone knows a better way to turn the AspectJ signature into a pretty string, please leave a comment.

    public void popMethod() {
        callStack.pop();
    }
 
    public void logCall() {
        if(callStack.size() < 2)
            return;
        String call = "\"" + top(1) + "\" -> \"" + top(0) +"\"";
        if(!callLog.contains(call)) {
            write(call);
            callLog.add(call);
        }
    }

Following a guard statement that protects the code from trying to log a call when only one method is on the stack, the code creates a description of the call in the format required by Dot for a graph edge, ie. the origin node in double quotes, followed by a stylised arrow, followed by the target node, again in double quotes.

If this call is not in the call log, the code writes it to the writer and then stores the call in the log so that it does not get written again.

    private Signature top(int i) {
        return callStack.get(callStack.size() - (i + 1));
    }
 
    private void write(String line) {
        try {
            writer.write(line + "\n");
            writer.flush();
        } catch(Exception e) {
            throw new RuntimeException(e);
        }
    }
 
}

Running some code, the unit tests in this example, will now create a file named “calls.txt” that contains all calls to methods that match the pointcut description in the aspect. The calls are written in Dot format but to make the output a valid input file for Dot a header and a closing bracket at the end are required.

It would be easy to write the required header when the writer is initialised but realistically it’s not possible to know when logCall is called for the last time, and thus it’s not possible to write the closing bracket from the Java code. Therefore…

Step 2 is a small shell script, or a script in your favourite scripting language, that wraps the required header and footer around the raw graph edges.

#!/bin/bash
 
cat <<-EOS
strict digraph G {
    graph [ ratio="auto compressed",
            rankdir="LR",
            ranksep=2,
            remincross="true",
            ];
    node  [ shape=box,
            style=filled,
            fillcolor=white,
            fontname=helvetica
            fontsize=10,
            fontcolor=black
            ];
EOS
 
cat calls.txt
 
cat <<-EOS
    }
EOS

I have an admission to make: This script is simplified and would not create the output I’ve shown further up. With a graph definition like this Dot would not put all unit tests nodes into the leftmost column but instead it would move them just left of the method they call. If, for example, test 1 called method A, which in turn called method B, and test 2 called method B directly, then test 1 would be in the first column, method A and test 2 in the second column and method B in the third column. The following UNIX command line wizardry, when added just below the cat calls.txt line in the script above, solves this problem. The explanation is left as an exercise to the reader…

echo '{ rank = same; '
fgrep Test.test calls.txt | awk -F " -> " '{ print $1 }' | sort -u | awk '{ printf "%s; ", $1 }'
echo '}'

I hope this article shows how two simple but powerful tools combined make it easy to create a really useful visualisation; and how clever but cryptic UNIX command lines can be.

SpringViz helps developers with what is at the heart of a Spring-based application, the container and the contexts files that describe the beans. In larger projects these context files can grow quite a bit. Newer versions of the Spring framework introduced features that help reduce the clutter and there are vast numbers of blog posts voicing different opinions on what should and what shouldn’t be in a context file but, no matter what, the number of beans in the context files will grow with the size of a project, and at some point it becomes difficult to understand the overall structure. This is no different from trying to maintain an understanding of a large codebase. In fact, I consider the context files to be code rather than configuration.

I’ve argued before (here and here for example) that to deal with the complexity and sheer size of software systems we need a 1000ft view. This is a view that uses visualisation techniques to aggregate large amounts of data and multiple metrics into one big picture. SpringViz provides that 1000ft view for Spring context files.

Let’s look at an example first. The following diagram shows the context files for the Spring JPetStore example application (click on the image for the full-size version):

I find that this diagram presents the architecture of the application quite nicely. The web controllers are defined in the petstore-servlet context in the top left and many of them have a dependency on the petStore bean, defined in the main application context. The petStore bean in turn has dependencies on all the DAOs, which are defined in the data access context. In that context we can clearly see how the top four DAOs share the same data source while the Order and Sequence DAOs use a different one. In addition to the individual dependencies we also get an impression of the overall architecture: a simple, multi-layered design with a single central choke point that acts as an adaptor between the presentation and data access layers.

From personal experience I can say that the bigger and more complex a system gets, the more valuable these diagrams become. In many cases they not only help share a common understanding of the architecture in the development team but they also help spot inconsistencies in the design and often trigger and support discussions around important restructurings. Ok, this is all I’m going to say to convince you to try out SpringViz. In the following paragraphs I’ll explain how to use it on your own projects.

Step 1: You need a copy of SpringViz. The version I’m discussing in this article can be downloaded here. When you unzip the archive you should have an Ant build file, a springviz folder with a few files in it and an example folder that contains the context files for JPetStore.

Step 1b: SpringViz uses GraphViz Dot to render the diagram. So, if you don’t have this on your system you need to download and install it. You should also open the build file and change the dot.command property to point to the Dot executable. On the Mac you should really get Pixelglow’s version of GraphViz.

Step 2: You can now run SpringViz by calling Ant with the default target. This will create a target folder, process the context files with the SpringViz XSLT sheet to create an input file for GraphViz Dot, and then invoke Dot to create beans.png, the final diagram.

Step 3: To integrate SpringViz into your own projects you can simply add the contents of the build file to your build file, place the springviz folder in an appropriate place, and adjust the configuration properties at the top of the build file.

If you are adventurous you can have a look at the Dot documentation and change the XSLT sheet to create slightly different input for Dot. You could colour the beans according to all sorts of criteria or you could change other aspects of their appearance depending on bean attributes.

There are a few limitations that you should be aware of: In its current version the system can’t deal with multiple beans with the same name defined in different contexts. So, if you have a defaultUrlMapping bean or similar in multiple files and you have dependencies to/from these the resulting diagram will be wrong. In this case it’s easiest to modify the style sheet to filter out the problematic beans. Another important point is that in its current form the sheet simply tries to use a bean’s id and name, which usually works out but will cause problems when beans have both, name and id. And lastly, the XSLT processor will need access to the web to fetch the schema files. I guess this can be avoided but so far this hasn’t been a problem for me.

If you missed the link above you can download the specific version of SpringViz discussed in this article from this site. The latest version of SpringViz as well as more documentation and resources are available on Mike Thomas’s site.

So far, we’ve mostly been using ad-hoc tools, made up from small building blocks such as GraphViz Dot and custom scripts to munge file formats. This can get you quite far, but how much further can you get with real tools?

With this question in mind, I visited Michele Lanza at the Univerity of Lugano when I was in Switzerland last week. I had been playing with his CodeCrawler for a while, especially since it started working with Java codebases courtesy of java2cdif, but I was curious what Michele and his PhD students are working on now.

The individual projects are a clear evolution of the ideas behind CodeCrawler, making use of interaction and filtering to cope with large amounts of data, and some of them add time as another dimension, which is interesting because I had also found identifying trends one of the most powerful uses of visualisation on several projects.

If you are interested in this field, have a look at Michele’s site, all the tools and related papers are linked from there.