In this last post I introduced you to some *very* basic understanding of how DGML works. Now I want to take that knowledge out for a test drive. :)

What I've decided to do is a couple of things. I've decided I'm going to show how to visualize Java code using Antlr and Visual Studio 2008 and output a DGML file that the VSTS 2010 Architecture product found in the latest CTP can render.

Why am I doing this? Because I think it will be an excellent example ( you'll be the judge of that ) of how easy it will be to visualize all kinds of data, not just .NET languages. Java code, Work Items, MSBuild dependencies, on and on. Literally, this list is potentially enormous, gated only by imagination and effort ( aren't all good things this way? ).

In some future posts, I'll show how you can continue to tweak the DGML to do some things that you can't do in the current CTP, but can with current bits ( such as node grouping, advanced selection, etc. ).

Prerequisites

If you want to follow along on this little journey, you need to get the following things:

  1. Visual Studio 2008
  2. Latest JDK from Sun. Lots of options here but I ultimately went here and followed the steps.
  3. Antlr 3.1.1 ( see below for instructions )
  4. VSTS 2010 CTP ( follow link for instructions )
  5. The Visual Studio 2008 solution that I used to create this post

Establish "Base of Operations"

I'm going to be very descriptive of what I'm doing 'cause the complication is not going to be in the implementation, but more in the "configuration of the parts".

  1. Create a directory where work will be done. This will be our "Base of Operations". From here on out, I'll refer to this directory as %BOO%.
  2. Download Antlr 3.1.1
    1. If this link becomes stale, go to http://www.antlr.org and download the latest source distribution which includes the runtime jars that you'll need.
  3. Extract the contents of the download to the %BOO% directory. When done, you should have the following contents in the %BOO%\antlr-3.1.1 directory:
    image
  4. Ensure Java is installed correctly
    1. Open up a command prompt, CD to your %BOO% directory.
    2. Type the following: java -?
    3. If you don't see a typical "Usage" statement, then you probably have something installed wrong. For me, I had to make sure that the java bin directory was in my path, so I added that to my system environment variables.
  5. Create a BOO.bat file that contains the following contents, and save to %BOO%:

    set BOO=%CD%
    set ANTLR_LIB=%BOO%\antlr-3.1.1\lib
    set classpath=.;%ANTLR_LIB%\antlr-3.1.1.jar;%ANTLR_LIB%\antlr-3.1.1-runtime.jar;%ANTLR_LIB%\stringtemplate-3.2.jar;%ANTLR_LIB%\antlr-2.7.7.jar
  6. Ensure Antlr is now ready to go.
    1. At the command prompt, type BOO.bat and hit enter
    2. Now type java org.antlr.Tool and hit enter
    3. You should see this:

      image
      If you don't, double check your BOO.bat file and make sure you don't have any typos.
  7. Feel free to download the original Java.g file also available on the Antlr site. I've included the one I have modified in the solution I've made available in the "Prerequisites section":
    1. Click here.
    2. If it looks like a page just full of text, right click and say view source, then "Save As..." java.g into your %BOO% directory.
  8. Unzip the solution I created into your %BOO% directory.
  9. You'll need to replace the references to antlr.runtime, Antlr3.Runtime, Antlr3.Utility, and StringTemplate to those now in your %BOO% directory:
    1. Add Antlr C# runtime references to the project.
      1. First we have to extract the runtime files found in the %BOO%\antlr-3.1.1\runtime\CSharp\dist\DOT-NET-runtime-3.1.1.zip.
        1. Extract the contents of that zip to %BOO%\antlr-3.1.1\runtime\CSharp\Libraries
        2. Once extracted, you should have a bin directory.
      2. Right click on the References node in the project
      3. Click on the Browse tab.
      4. Navigate to %BOO%\antlr-3.1.1\runtime\CSharp\Libraries\bin\net-2.0
      5. Add all the dlls found in that directory as references. There should be four dlls in there, as mentioned above ( If you do everything I've just mentioned just right, this step shouldn't be necessary, as the solution I provided should be relative )
  10. OK, we're ready to build.
    1. Rebuild the solution.
  11. If all went well, you now have a parser that's ready to parse Java 1.5 code!

Results

The executable created after building the solution is Java2DGML.exe. If you drop to the command line, CD into the debug directory where the exe is found, run the following command:

Java2DGML.exe /f %BOO%\antlr-3.1.1\src\org\antlr\Tool.java > Tool.dgml

then open Tool.dgml in the VSTS 2010 CTP, here's what you'll see:

image

Here's the XPS file of that image as well.

The exe is by no means a robust piece of software. It currently understands how to gather information for simple Java classes ( i.e., not templated ), fields, and methods. No interfaces, enums, etc., but after this post, you should have all the info you need to take this example a bit farther.

Now let me explain the source a little bit...

Taxonomy of the Solution

Here is a shot of the Solution Explorer with the Java2DGML solution loaded:

image

Generated Files

Java.Tokens, JavaLexer.cs, and JavaParser.cs are all generated files. You can regenerate those files by executing the following command in you command window where you executed BOO.bat, in the %BOO%\Java2DGML\Java2DGML directory:

java org.antlr.Tool Java.g

Java.g

The Java.g file is where the grammar for parsing Java 1.5 is defined. This grammar file instructs the org.antlr.Tool object how to generate a parser in C# capable of parsing Java 1.5 code. More on this later.

DGMLContext.cs

A simple utility class used to gather information during the parse that is later used to generate the appropriate DGML. For every Java class, one DGMLContext object will be created to capture the relevant details.

DGMLFile.st

Antlr has a great mechanism built in called the StringTemplate framework. Check out this link for more details. This file is an example of a StringTemplate for DGML files. More on this later.

JavaParserImpl.cs

Antlr allows the C# developer to tell Antlr to create a partial class for its parser implementation so that additional behavior can be added and used in the grammar file more easily. I've taken advantage of that in this file.

Program.cs

This is the main program, where all the pieces come together.

 

Summary

This post is really meant to whet your appetite on some of the possibilities coming in the 2010 version of the Architecture product around visualization. Admittedly, I'm clearly just scratching the surface of this particular example ( Java source visualization ), but that's ok. From time to time, I may come back to this example and flesh out a little more in order to exemplify some deeper features.

In the meantime, I think in my next post I'll start to show some more of the features inherent in DGML, beyond just the simple nodes and links I've shown to date.

Stay Tuned!