Agile Zone is brought to you in partnership with:

Meera has posted 70 posts at DZone. You can read more from them at their website. View Full User Profile

Reverse-engineer Source Code into UML Diagrams

08.22.2008
| 163439 views |
  • submit to reddit

I have been on several teams where we studiously designed UML diagrams at the beginning of the project. As the project progressed, and deadlines approached, the UML diagrams were left somewhere behind, not to be updated in months. When a new developer joined the team, we showcased the old UML diagrams, and kept telling "Oh, we never had time to update them, please see the source code to get an idea. And, don't hesitate to ask if you have any doubt's". I am sure, you all have gone through the same scenario.

However, we don't have to keep making up stories anymore, since this article shows how easy and simple it is to include UML diagrams within your Javadoc and also keep them updated with every change in the source code repository. We can do these in less than a few minutes, and in a few simple steps.

Getting started with UmlGraph takes five steps:

  1. Download the source code for UMlGraph.
  2. Download and install Graphviz.
  3. Make changes to your Ant build file.
  4. Run the Ant target.
  5. Add this target to your CI job.

Step 1: Download the source code for UMLGraph from here. Unzip the contents. To compile the Java doclet from the source code run ant on the build.xml file. Copy the UmlGraph.jar file to your projects library. If there is a version mismatch between the different versions of JDK you are using you get an exception like this:

java.lang.UnsupportedClassVersionError: Bad version number in .class file

Make sure you recompile the UMLGraph source code, and copy the library to your project.

Step2 : Download and install Graphviz from here. The dot file needs to be post-processed with Graphviz to produce the actual UML diagram. Running the UmlGraph doclet will generate a Graphviz diagram specification that can be automatically processed to create png drawings. You can also generate other formats using Graphviz as well. If Graphviz isn’t installed you will get an exception as shown below:

BUILD FAILED
/Users/meerasubbarao/Development/webservices-samples/build.xml:107:
Execute failed: java.io.IOException: dot: not found
Total time: 269 milliseconds


Step 3. Changes to your build.xml file.
Assuming you already have a working project, with Ant build file. Add the following target to your build.xml file as shown below:

<target name="javadocs" depends="build" description="generates javadoc and also UML Diagram">
<mkdir dir="${reports.dir}/javadoc"/>
<javadoc sourcepath="${src.dir}" packagenames="com.stelligent.*" destdir="${reports.dir}/javadoc"
classpathref="java.classpath" private="true">
<doclet name="org.umlgraph.doclet.UmlGraphDoc"
path="lib/UMLGraph.jar">
<param name="-attributes" />
<param name="-operations" />
<param name="-qualify" />
<param name="-types" />
<param name="-visibility" />
</doclet>
</javadoc>
<apply executable="dot" dest="${reports.dir}" parallel="false">
<arg value="-Tpng"/>
<arg value="-o"/>
<targetfile/>
<srcfile/>
<fileset dir="${reports.dir}" includes="*.dot"/>
<mapper type="glob" from="*.dot" to="*.png"/>
</apply>
</target>

 

A number of options contol the operation of UMLGraph class diagram generator. These can be specified as parameters within your build file as shown above.

Details about a few options are:

-output
Specify the output file (default graph.dot).
-d
Specify the output directory (defaults to the current directory).
-qualify
Produce fully-qualified class names.
-horizontal
Layout the graph in the horizontal direction.
-attributes
Show class attributes (Java fields)
-operations
Show class operations (Java methods)
-constructors
Show a class's constructors
-visibility
Adorn class elements according to their visibility (private, public, protected, package)
-types
Add type information to attributes and operations
-enumerations
Show enumarations as separate stereotyped primitive types.
-enumconstants
When showing enumerations, also show the values they can take.
-all
Same as -attributes -operations -visibility -types -enumerations -enumconstants

Take a look here for more options.

Step 4. Run the ant target:
Open a command window and run the ant target: ant javadocs and you should see output as such in your console window:

meera-subbaraos-macbook-9:webservices-samples meerasubbarao$ ant javadocs
Buildfile: build.xml

init:

cleanGenerated:

build:
[javac] Compiling 22 source files to /Users/meerasubbarao/Development/ci-jobs/jobs/PetStore_Nightly/workspace/webservices-samples/classes
[javac] Note: Some input files use unchecked or unsafe operations.
[javac] Note: Recompile with -Xlint:unchecked for details.

javadocs:
[javadoc] Generating Javadoc
[javadoc] Javadoc execution
[javadoc] Loading source files for package com.stelligent.biz.ws...
[javadoc] Loading source files for package com.stelligent.ent.jpa...
[javadoc] Constructing Javadoc information...
[javadoc] UmlGraphDoc version 5.0, running the standard doclet
[javadoc] Standard Doclet version 1.5.0_13
[javadoc] Building tree for all the packages and classes...
[javadoc] Building index for all the packages and classes...
[javadoc] Building index for all classes...
[javadoc] Generating /Users/meerasubbarao/Development/ci-jobs/jobs/PetStore_Nightly/workspace/webservices-samples/reports/javadoc/stylesheet.css...
[javadoc] UmlGraphDoc version 5.0, altering javadocs
[javadoc] Building Package view for package com.stelligent.biz.ws
[javadoc] Building Package view for package com.stelligent.ent.jpa
[javadoc] Building Context view for class com.stelligent.biz.ws.SupplierManagerBean
[javadoc] Building Context view for class com.stelligent.biz.ws.SupplierManager
[javadoc] Building Context view for class com.stelligent.biz.ws.SignonManagerBean
[javadoc] Building Context view for class com.stelligent.biz.ws.SignonManager
.....

BUILD SUCCESSFUL
Total time: 8 seconds
meera-subbaraos-macbook-9:webservices-samples meerasubbarao$

 

The javadoc generated is pretty neat with UML diagrams on the top:

Step 5: Add this target to your CI Job.
If you already have a CI server like Hudson up and running, which runs commit builds and nightly builds, adding this new target is a one step process. In my case, I already have a nightly job running, I added this ant target to my default target as shown below:

<target name="all" depends="cleanAndDeployForCoverage, javadocs" />

Next, force a build on the Hudson job, publish the javadocs, and you can see the results on the hudson dashboard.

The Javadoc embedded with UML diagrams displayed from within the Hudson dashboard:

Now that we have UML diagram integrated within our build file, and also our CI job, we can ensure that our code base and the UML diagrams are always in sync. We saw how to include these ant targets in our commit builds or nightly builds of our CI jobs, and also published these artifacts as part of our post build process.

 

Resources:

Published at DZone with permission of its author, Meera Subbarao.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Harpreet Sardar replied on Thu, 2011/03/10 - 1:28pm

I am newbee to java, and this is an excellent article.

Thank you

Harry Laou replied on Tue, 2011/03/29 - 6:38am

@Diomidis It's great to see that despite your administrative tasks in GGPS you are still active in developing. Thank you for your contribution.

Dan Cristoff replied on Fri, 2011/04/08 - 3:33pm

we will try it thanks. adidasi puma nike 

Sofia Tah replied on Fri, 2011/05/13 - 5:27pm

Hi Everyone/Meera, I am using Eclipse and I would like to know how can I generate UML for javacode in Eclipse. I have never used ANT before in Eclipse. Any help will be highly appreciated. Thanks

Cheenu Junk replied on Wed, 2011/06/08 - 5:00pm

wonderful. Its really good. But you forgot to mention about the errors with dot.

If dot.exe is not found in the path, place it in the java_home\bin, it should be fine. 

But still i received problem with the execution as the .dot file needs to be converted to .png file. You can do this manually using a dos / shell script. 

 There should be a way in ant to do this, let me reply if i can find one. This looks really good. 

 Thanks anyways.

Mikael Petterson replied on Fri, 2011/06/10 - 8:59am

Hi,

 Great article and very helpful. I have a quick question about the report files that are created.

1. Do the report files need to located in Hudson/Jenkins workspace?

2. Do Hudson/Jenkins  need a specific plugin installed?

 

br,

 

//mike

Edward Garson replied on Sat, 2011/10/01 - 7:55pm

Excellent article

Sagar Joshi replied on Sun, 2011/10/16 - 4:20pm

Hello everyone! im a newby to java! An outstanding article but i have a problem!

 

I copied the path to the build.xml in the project folder.

 

When i try to ant it say build does not exist in the project it is used by target javadocs!

 

Please Help Me.

Carla Brian replied on Fri, 2012/05/04 - 7:01pm

Good thing I stumbled upon in this post. This is very helpful. I will study more on this, since this is my first time using this one. What I like about this also is that it is free source. - James P Stuckey

Aaron Dixon replied on Sat, 2012/05/26 - 11:08am

Heatlamp (single install) generates interactive sequence diagrams from running Java code.

http://www.jmolly.com/heatlamp/ 

Naresh Babu replied on Fri, 2012/11/16 - 5:08am

Thanks a lot for Nice article and I was able to configure this to my project successfully.

But we need to change doclet and JAR names as shown below to make it work.

<doclet name="gr.spinellis.umlgraph.doclet.UmlGraphDoc" path="${basedir}/common/lib/UmlGraph.jar">


Robin Knipe replied on Mon, 2013/02/04 - 1:49pm in response to: Meera Subbarao

Hi - very useful article, thanks a lot!

On the subject of javascript though, I have been trying to get the dot program to output .svg files instead of .png files (using the below apply tag), so that I can add interactive scripting utilities in javascript. I updated the 'apply' tag to the following, but dot just resolutely keeps producing .png files! Any idea how I can get the result I'm looking for?

Thanks, Robin.

<apply executable="dot" dest="${doc}" parallel="false">
	<arg value="-Tsvg" />
	<arg value="-o" />
	<targetfile />
	<srcfile />
	<fileset dir="${doc}" includes="*.dot" />
	<mapper type="glob" from="*.dot" to="*.svg" />
</apply>

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.