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.

About a year ago, in a discussion about architects, rather than trying to define what an architect is or does, we looked at what he or she should know. We expressed our ideas as mini-essays, strictly limiting ourselves to one per essay, and it turned out that, at least to my surprise, there was a lot of agreement; maybe because we hadn’t come up with hard and fast rules but with ideas and guidelines.

Luckily Richard Monson-Haefel was part of that discussion and he had the resolve and means to make our thoughts more widely available. Our list of the 97 things every architect should know was collected and refined on this wiki, and is available under a creative commons license. For a more convenient read it has now also been published as a book by O’Reilly. As expected, the discussions have begun.

Check out the JAOO Australia site for information on the sessions, and sign up for your city if your interested!

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.

Let’s look at an example. CCMenu is a small application that displays the status of CruiseControl continuous integration servers. As part of adding a new project to be monitored the user has to enter the URL for the CruiseControl server and a combox provides a history of previously used servers.

The same dialog has a matrix of buttons to set the type of the server. Actually, by default CCMenu detects the server type automatically but that’s beside the point. What we’re interested in is the piece of functionality that is responsible for selecting the correct server type for the URL chosen by the user. In our case, this would be Cruise Control Dashboard.

One difference between Cocoa and most other UI frameworks is the fact that the user interface is stored by serialising the objects, rather than generating code. For this reason I’m happy to not insist on test-first for the actual interface. What I do want to test is the code in the controller classes.

Obviously, I could load the serialised objects, locate the elements involved and then use methods such as performClick: to trigger the actions. Sounds convoluted? Yes, I agree. Luckily there’s a better way.

This is a case where testing is tricky because the object under test interacts with objects that are difficult to deal with. In such cases dynamic mock objects have proven extremely useful. A good introduction can be found here and mockobject.com lists papers and implementations. For Objective-C I created OCMock. Let’s look at how this helps us testing our controllers.

Here are the relevant parts of the interface declaration of the controller. Given that I’m doing test-driven development there’s currently no implementation of the methods. I simply created the interface of the controller based on my needs while designing the dialog.

@interface CCMPreferencesController : CCMWindowController
{
    IBOutlet NSComboBox *serverUrlComboBox;
    IBOutlet NSMatrix *serverTypeMatrix;
}

- (IBAction)historyURLSelected:(id)sender;

In my test I want to use mock objects instead of loading the actual user interface. So, in the test setup, after creating my controller, I create appropriate mock objects and set up the controller to use these.

@implementation CCMPreferencesControllerTest

- (void)setUp
{
    controller = [[[CCMPreferencesController alloc] init] autorelease];
    serverUrlComboBoxMock = [OCMockObject mockForClass:[NSComboBox class]];
    [controller setValue:serverUrlComboBoxMock forKey:@"serverUrlComboBox"];
    serverTypeMatrixMock = [OCMockObject mockForClass:[NSMatrix class]];
    [controller setValue:serverTypeMatrixMock forKey:@"serverTypeMatrix"];
}

You notice that I’m using key-value coding to set the variables (outlets). I’m doing this because the variables are not public and at the same time I don’t want to write accessor methods for them.

Now, we can start writing the actual test for the functionality. Have a look at the full test first.

- (void)testSelectsServerTypeWhenHistoryURLIsSelected
{
    NSString *selectedUrl = @"http://localhost/cctray.xml";
    [[[serverUrlComboBoxMock stub] andReturn:selectedUrl] stringValue];
    [[serverTypeMatrixMock expect] selectCellWithTag:CCMCruiseControlDashboard];
    [controller historyURLSelected:nil];
}

What’s going on here? Firstly, I tell the mock object that stands in for the actual combox box that it should stub the stringValue method. This means that when somebody invokes stringValue on this object it will return the string @”http://localhost/cctray.xml”. This is all we’d have done with the real combo box anyway.

Secondly, I tell the mock that stands in for the server type matrix that it should expect that the method selectCellWithTag: is called with CCMCruiseControlDashboard as an argument.

Lastly, I invoke the method I want to test. What happens, once the implementation is complete, is that the code will go the the combo box and ask it for its string value. The first mock will return the stubbed value. Now, the code should do whatever it needs to do to figure out which server type this corresponds to and then set that in the server type matrix by selecting the cell with the appropriate tag, and this is what we’ve told the second mock to expect.

Wait, you might say, we don’t have an implementation yet. So, how does this test fail? It doesn’t yet. We’ll have to tell the mock objects to verify that everything we told them to expect actually occurred, and a logical place for this is the test tearDown.

- (void)tearDown
{
    [serverUrlComboBoxMock verify];
    [serverTypeMatrixMock verify];
}

Strictly speaking, we don’t have to verify the combo box mock because it doesn’t have any expectations but it’s good practice to verify all mocks in the tear down, especially if the same mocks are used for multiple tests. By the way, by default the mocks also have fail-fast behaviour; when they receive a method that wasn’t stubbed or expected, they raise an exception right away. Detecting something that wasn’t expected can be done right way, detecting that something that was expected didn’t occur must be trigger by the user.

Now, if we run this test with an empty implementation of historyURLSelected: it will fail when we tell the server type matrix mock to verify because the expected method hasn’t been called. The error message will look something like this:

Unknown.m:0: error: -[CCMPreferencesControllerTest testSelectsServerTypeWhenHistoryURLIsSelected] : OCMockObject[NSMatrix]: expected method was not invoked: selectCellWithTag:0

Adding an implementation like the following one adds the right functionality and makes our test pass.

@implementation CCMPreferencesController

- (void)historyURLSelected:(id)sender
{
    NSString *serverUrl = [serverUrlComboBox stringValue];
    [serverTypeMatrix selectCellWithTag:[serverUrl cruiseControlServerType]];
}

In summary, testing controllers becomes relatively easy when we follow this pattern:

1. Replace all UI elements with mocks; using key-value coding to access the outlets.

2. Set up stubs with return values for UI elements that the controller will query.

3. Set up expectations for UI elements that the controller should manipulate.

4. Invoke the method in the controller.

5. Verify the expectations.

I find tests following this pattern easier to write and understand than tests that load a NIB file and interact with the actual user interface elements.