Code Visualisation with Relief

A colleague recently pointed me in the direction of an interesting code visualisation application called Relief. The purpose of the tool is to analyse a Java project and present the objects therein as a 3D model with various characteristics to show size, client/provider dependencies and frequency of use. I had some spare time this week so decided to use Relief to visualize the KeyStore Explorer (KSE) project code.

The set up process for Relief is relatively straightforward. You’ll need JRE 1.5+ and Java3d 1.5+. I plumped for Java 1.6 and Java3d 1.5.2. I had to use the Windows installer for Java3d  as, try as I might, I couldn’t get Relief to find a manual install. Another tip is to make sure that you run Relief with the JRE that Java3d installs itself into.

Once installed Relief requires an xml configuration file which points it in the direction of the project source to analyse and any dependant libraries. Here is the config file I created for KSE:

<parser name="JavaParser">
  <driver>org.workingfrog.relief.plugins.java.JavaConfigHandler</driver>
  <projects default="kse">
    <project name="kse">
      <jrePath jreVersion="1.6">C:\Program Files\Java\jdk1.6.0_23\jre</jrePath>
      <basedir>C:\projects\kse</basedir>
      <!--blackbox /-->
      <build>bin</build>
      <src>
        <path>src</path>
      </src>
      <lib show="false">
        <fullpath>C:\projects\kse\lib\AppleJavaExtensions.jar</fullpath>
        <fullpath>C:\projects\kse\lib\bcmail.jar</fullpath>
        <fullpath>C:\projects\kse\lib\bcprov.jar</fullpath>
        <fullpath>C:\projects\kse\lib\binor.jar</fullpath>
        <fullpath>C:\projects\kse\lib\jh.jar</fullpath>
        <fullpath>C:\projects\kse\lib\junit.jar</fullpath>
        <fullpath>C:\projects\kse\lib\looks.jar</fullpath>
      </lib>
    </project>
  </projects>
</parser>

Fortunately KeyStore Explorer has very few dependencies. Note the commented out ‘blackbox’ element. Relief will analyse dependencies based on either interfaces alone (blackbox) or implementation. Running Relief against the config file involves running a simple command line:

java -jar relief.jar kse.xml kse

If a dependency is missed a ClassNotFoundException will be displayed in the console and Relief will freeze on its splash screen. To fix this simply kill it, add the missing dependency indicated by the exception and re-run. Once all dependencies have been included the Relief should start with no errors.

I ran the tool with black-box switched off as I wanted to see the true dependency picture in all its ugliness. The project code is analysed on start up and the analysis  is very fast. The time to start Relief for the KSE project was 15 seconds on my Macbook Air running Windows 7. That is impressive given that the KSE code base is made up of 286 classes over 33 packages and encompasses ~37,000 lines of code.

After analysis completes Relief displays an impressive 3d model:

Click to enlarge

The screenshot above shows each KSE package as a cube and dependencies between packages as gradiated lines coloured from green to blue (green for the provider, blue the client). Some other key features visualised are:

• The bigger the package’s cube the more classes and interfaces the package contains.
• The closer to the centre of a diagram a package is the more it is utilised (see grey concentric circles for reference).
• The lower down a package is the more dependencies it has on other packages.

Using a mouse it is a simple matter to rotate, pan, zoom and move the 3D model to focus in on a particular area. In addition double-clicking on any package will bring up a diagram featuring the same visualisations for the package’s contents. Relief contains a few other options I haven’t played with yet including set operators and the ability to show dependencies to third party library entities and to the Java Standard API itself.

The author of Relief touts it as a ‘design tool’. I would not go as far as that as I don’t see myself using it as part of my development process. It is, however, a cool tool that appeals to my inner geek. If I was to take a picture of KSE’s code to put on my wall (which I would never do, I’m a geek not a complete saddo) then I would use Relief as the camera.