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
| 171899 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

Arvind Saraf replied on Fri, 2008/08/29 - 2:00pm

Does not seem to work on Java 1.4? After I got the 'unsupported version' error, I tried to build from the umlgraph source. It failed at the javac invalid flag error. Do I have to use some older version or something to work with 1.4?

Diomidis Spinellis replied on Fri, 2008/08/29 - 3:09pm in response to: Arvind Saraf

The last version that is compatible with Java 1.4 is UmlGraph package version 2.10.  It is available on the downloads page.  Look at the documentation of that version for what features were supported at that time.

Antti Kekki replied on Fri, 2008/09/05 - 7:08am

There is misbehavior in build.xml example. The "<apply executable="dot">" section is not needed beacause the <javadoc> section creates png-files automatically. There is also one syntax error in this section:

Original:

<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>
This actually doesn't do anything because <fileset> tag include parameter only searches .dot files from root folder of ${reports.dir}. Fileset tag needs to be changed from
<fileset dir="${reports.dir}" includes="*.dot"/>
to
<fileset dir="${reports.dir}" includes="**/*.dot"/>

Now it searches .dot files from subfolders of ${reports.dir}.

Gian Franco Casula replied on Tue, 2008/09/09 - 4:56am

Hi Meera,

Thanks a lot for this article, and efharisto to Mr. Spinellis too!

I managed to change my build script which builds locally on the command line (Win XP) and it works perfectly.

On the CI server (Linux) I have a little problem still, and I was hoping you guys could help me out...

The build script is exactly the same as my local script, but during the execution of the <apply executable="dot"...> bit, some errors occur of which this is one of them...

java.io.IOException: Cannot run program "dot": java.io.IOException: error=2, No such file or directory

Do you have any idea?

Gian

p.s. the error list is much longer, but I didn't include it for readability... 

Guillaume Jeudy replied on Fri, 2008/09/12 - 7:49am

I tried using the maven integration as described in a previous comment. It works fine but I noticed that in my multi-module maven project each javadoc/UML set is generated independently of each other so if I have a class in my UML diagram that refers to another submodule it will give a page not found when I click on the class.

 I tried javadoc:aggregate but it fails with the following exception:

[INFO] An error has occurred in JavaDocs report generation:Exit code: 1 - javado
c: error - In doclet class org.umlgraph.doclet.UmlGraphDoc,  method start has th
rown an exception java.lang.reflect.InvocationTargetException
java.lang.AssertionError: cannot find method org.testng.annotations.Test.groups(
)
        at com.sun.tools.javac.jvm.ClassReader$AnnotationDeproxy.findAccessMetho
d(ClassReader.java:1074)

 Can other maven users share with their experience?

 Thanks,

-Guillaume Jeudy

Ricky Clarkson replied on Tue, 2008/09/23 - 3:56am

I find that the suggestions here for using the Maven UMLGraph plugin all fail.  This almost works for me, reverse engineered from browsing the Maven repository.  Specifically, while gr.spinellis might have been renamed to org.umlgraph, but that doesn't seem to exist in the central Maven repository.  Also, someone mentioned that 5.0 was released, but in the gr.spinellis section of the central repository, the maximum version is 4.6.  So here's some XM Hell:

            <plugin>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.3</version>
                <configuration>
                    <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
                    <docletArtifact>
                        <groupId>gr.spinellis</groupId>
                        <artifactId>UmlGraph</artifactId>
                        <version>4.6</version>
                    </docletArtifact>
                    <additionalparam>
                        -inferrel -inferdep -quiet -hide java.* -collpackages java.util.* -qualify -postfixpackage -nodefontsize 9
                        -nodefontpackagesize 7
                    </additionalparam>
                </configuration>
            </plugin>

 The reason this ultimately fails is:

Embedded error: Error rendering Maven report: Exit code: 1 - javadoc: error - Cannot find doclet class org.umlgraph.doclet.UmlGraphDoc

I thought Maven plugins were supposed to know their own dependencies.

Shih-Chia Wang replied on Tue, 2008/10/14 - 8:06pm

So nice article. I think there are a lot of skill that I need to learn~

Thanks.

Richard Cowin replied on Fri, 2008/10/24 - 5:05am

I got it to work in Maven by upgrading to maven 2.0.9 and using:

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <configuration>
                    <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
                    <docletPath>path\to\UmlGraph.jar</docletPath>
                    <additionalparam>-views</additionalparam>
                </configuration>
            </plugin>
 

Meera Subbarao replied on Fri, 2008/10/24 - 12:18pm in response to: Richard Cowin

[quote=cowinr]

I got it to work in Maven by upgrading to maven 2.0.9 and using:

[/quote]

Thanks for sharing, Richard. I am sute it will help many Maven users.

Meera Subbarao

Sundaram Gnanavel replied on Fri, 2008/10/24 - 3:50pm

It's worth reading and try. 

Finally, i'm able to pull this using Maven. I think, UMLgraph and GraphViz works with both Maven 2.0.8 and 2.0.9. I've used UMLGraph 5.1, graphviz 2.21 using JDK 6. 

Here is the maven snippet and don't forget to run the "site" lifecycle. "mvn  clean compile site"

<-------------->

     <reporting>

        <plugins>

            <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-javadoc-plugin</artifactId>

                <reportSets>

                    <reportSet>

                        <id>uml</id>

                        <configuration>

                            <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>

                            <docletArtifact>

                                <groupId>org.umlgraph</groupId>

                                <artifactId>doclet</artifactId>

                                <version>5.1</version>

                            </docletArtifact>

                            <additionalparam>-operations</additionalparam>

                            <additionalparam>-qualify</additionalparam>

                            <additionalparam>-types</additionalparam>

                            <additionalparam>-visibility</additionalparam>

                            <additionalparam>-collpackages</additionalparam>

                            <destDir>withUML</destDir>

                            <show>private</show>

                        </configuration>

                        <reports>

                            <report>javadoc</report>

                        </reports>

                    </reportSet>

                </reportSets>

            </plugin>

        </plugins>

    </reporting>    

<---------------> 

 - Sundar

MahaNagarjuna A... replied on Thu, 2008/12/04 - 6:11am

Hi,

Is it possible to generate "Sequence" diagrams using "javadoc" doclet?

 

- Nagarjuna

horri khalid replied on Mon, 2008/12/15 - 6:37am

I appreciate your work, but I still have this problem: java.io.IOException: Cannot run program "dot": CreateProcess error=2. note that the Graphviz is  installed 

So how can I resolve this pb?

other question how the java.classpath is defined in the ant file.

thnx 

Serge Simon replied on Tue, 2008/12/16 - 5:02am

I really think that UMLGraph is a very good tool.

The only problem for me is with the Graphviz dependency : i would like to runUMLGraph on platforms where Maven runs, but I *can't* install graphviz on these servers (i have no root access and can't install anything / i'm not supposed to).

Is there a way to convert .dot files to .png in java rather than relying on Graphviz ? That would be perfect for me to have a full java chain for producing these uml graphs.

I've found UMLJgraph ( see http://michael.rumpfonline.de/2005/08/13/umljgraph/ ) but the project seems discontinued and i haven't been able to run UMLJGraph without strange errors even with the simple ant example provided for UMLJGraph (NullPointer in XmiRepository.init() ...) ...

Any ideas for replacing Graphviz with something else easier to install ?

Diomidis Spinellis replied on Tue, 2008/12/16 - 5:39am in response to: horri khalid

Please verify that you can run dot from the command line.

Diomidis Spinellis replied on Tue, 2008/12/16 - 5:44am

(In reply to the comment asking about the possibility of removing the GraphViz dependency.)

At about 226,000 lines of code and with 15 years of history behind it Graphviz is a very large and mature body of code.  I don't think it's easy to replace it with something else.

Serge Simon replied on Tue, 2008/12/16 - 6:21am

Hello ; of course I fully understand that the replacement of Graphviz in UMLGraph would at least not be easy, starting from scratch to develop this functionnality inside UMLGraph.

I was just asking if somone was aware of a Java project capable of transforming .dot to .png (or .jpg, ...) in pure Java rather than relying on a platform dependent tool. Some kind of a JGraphViz, or at least a subset of the GraphViz functionnalities - juste what is needed for the conversionof the .dot. The idea would have been to keep UMLGraph exactly like it is, but to use something else to convert .dot to .png (even if developping a tool for doing this may be rather difficult, too).

horri khalid replied on Wed, 2008/12/17 - 3:47am in response to: Diomidis Spinellis

Thanx for your replay Diomidis

 

Yes I can

I think the problem come from classpathref, and I want how to define this attribute?

really I am not familiar with ant and this is my first contact with umlgraph and Graphviz 

horri khalid replied on Wed, 2008/12/17 - 5:41am

I think the ant cannot execute the "dot" because my project is in disk d:\ and Graphviz is installed in c:\

when I copy class.dot file to c:\ and run the dot I get a class.png, Any help?

sudheer kancherla replied on Wed, 2009/10/21 - 3:13am

i am not able to use it it is giving the following error..any help plz: "Ensure that dot is in your path and that its path does not contain spaces javadoc: warning - Could not find map file D:\workspace\Struts\srcc\${reports.dir}\" what is dot i have installed graph viz..after that am i need to set any path.

aneesh singh replied on Wed, 2009/11/11 - 2:47am

this is a great article but somehow i am a novice in this field and its not working for me... please can someone send a full package. I will be very greatful.

Fabrice Delhoste replied on Tue, 2009/12/15 - 5:49am

Hi,

I have some problems using @opt when generating Javadoc for my project.

Actually, the problem is that it does not take any of my @opt into account (but all others such as composed, ... are ok). I even tried to run the UmlGraph javadoc test suite but it seems somewhat broken and after fixing things, the behavior is the same with the UmlGraph distribution.

I tried a lot of things (operations, attributes, colors, fonts) but it definitely fails. My diagrams are simply generated but using the parameters provided in the command-line. 

Any idea what can cause that?
Because I haven't found kind of support forums or any direct contact to the author...just this article.

Thanks in advance if you can help.

 

Adesh Yasoda replied on Mon, 2010/03/08 - 3:49pm

This article is really good. It helps a lot for reverse engineering. Thanks Adesh

Alexey Zavizionov replied on Tue, 2010/04/13 - 9:46am

Here is my blog post http://zavizionov.blogspot.com/2008/12/reverse-engineer-source-code-into-uml.html it will be very helpfull for you! Regards, Zavizionov.

Syed Ali Naqvi replied on Mon, 2010/04/19 - 3:33pm

If you want to reverse engineer a java program to generate sequence diagrams you can use the Java Call Tracer tool on SourceForge

 http://sourceforge.net/projects/javacalltracer/

Diomidis Spinellis replied on Mon, 2010/05/24 - 3:07am

Version 5.3 of UMLGraph has been release.  This version provides new features and bug fixes.

 

  • Sequence diagrams provide an option to specify whether objects are underlined or not.
  • Documentation generated with UMLGraph will process correctly non-ASCII characters. (Fix contributed by Gunho Kim.)
  • New -dotexecutable option allows the explicit specification of dot's location. (Contributed by Laird Nelson.)
  • UmlGraphDoc will obey the options specified through @opt tags within Java files. (Contributed by Laird Nelson.)
  • Use a logical font rather than a font file name for italics. This fixes a problem with unresolved fonts under Windows and modern versions of Graphviz. (Suggested by Przemyslaw Szufel.)
  • Support for javadoc's -linkoffline option. (Contributed by Nikita Kozlov.)
  • Do not show relations of hidden fields. (Fix contributed by Cimballi.)

 

Chaitali Mt replied on Sun, 2010/12/19 - 10:46pm

do I need to install eclipse? then try......? "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." where's the ant file & how to run it on build.xml? also how to copy .jar to project library? I'm poor in java but I need it. please help me.

Diomidis Spinellis replied on Sat, 2011/01/08 - 1:37pm

I just released version 5.4.  This version creates clickable diagram elements in HTML content, makes the generation of diamond shapes compatible with GraphViz 2.27, and includes a fix to ensure that class images only appear once in the generated diagrams.  Many thanks to all the contributors.

Diomidis Spinellis replied on Sat, 2011/01/08 - 1:39pm

I just released version 5.4.  This version creates clickable diagram elements in HTML content, makes the generation of diamond shapes compatible with GraphViz 2.27, and includes a fix to ensure that class images only appear once in the generated diagrams. Many thanks to all the contributors.

Java Chandu replied on Sat, 2011/02/05 - 10:45pm

Hi All

I'm trying to generate .dot file but it is not. I've following code in my pom.xml and commandline as "mvn clean compile site"

-------------------------------------------------------------------------------------------------------------

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <reportSets>
        <reportSet>
          <id>uml</id>
          <configuration>
            <doclet>gr.spinellis.umlgraph.doclet.UmlGraph</doclet>
            <docletpath>
            D:/UMLGraph-5.4/lib/UmlGraph.jar</docletpath>
            <docletArtifact>
              <groupId>gr.spinellis</groupId>
              <artifactId>UmlGraph</artifactId>
              <version>4.3</version>
            </docletArtifact>
            <additionalparam>-views</additionalparam>
            <destDir>target/uml</destDir>
            <show>private</show>
          </configuration>
          <reports>
            <report>javadoc</report>
          </reports>
        </reportSet>
        <reportSet>
          <id>html</id>
          <configuration>
            <show>private</show>
          </configuration>
          <reports>
            <report>javadoc</report>
          </reports>
        </reportSet>
      </reportSets>
    </plugin>
  </plugins>
</reporting>
 

-------------------------------------------------------------------------------------------------------------

Can you please let me know whats wrong here?

Thanks

 

Jean-claude Stritt replied on Mon, 2011/02/14 - 6:05am

Hi,

I use last version of UMLGraph (5.4) and try to make an ANT task to process javadoc after a compilation in Netbeans. All is fine, but UMLgraph not takes @opt values that i give in my classes, but in your release comments (5.3), you say "UmlGraphDoc will obey the options specified through @opt tags within Java files. (Contributed by Laird Nelson.)". What must I do ?

A class with @opt :

/**
 * @opt all
 * @opt nodefillcolor lightblue
 * @has 1 - 1 FenetreSansBarre
 * @has 1 - 4 FenetreAvecBarre
 * @depend - - - ScreenInfo
 * 
 */
public class Main {
   ...
}

My ant task :

 <target name="-post-compile">
  <property name="src.dir" location="src"/>
  <property name="reports.dir" location="reports"/>
  <property name="umlgraph.dir" location="${user.home}/Dropbox/_DEV/Java/ExtraLibs/umlgraph/lib"/>
  <property name="dot.dir" location="/usr/local/bin"/>
  
  <mkdir dir="${reports.dir}/javadoc" />
  <javadoc
  sourcepath="${src.dir}"
  packagenames="app.*"
  destdir="${reports.dir}/javadoc" >

<tag name="tagvalue" description="UMLGraph additional annotation:" /> <tag name="has" description="UMLGraph relationship information:" /> <tag name="depend" description="UMLGraph relationship information:" /> <tag name="hidden" description="UMLGraph hidden entity:" /> <tag name="stereotype" description="UMLGraph stereotype information:" /> <tag name="match" description="UMLGraph name matching pattern:" /> <tag name="opt" description="UMLGraph view option:" /> <tag name="view" description="UMLGraph view:" /> <doclet name="org.umlgraph.doclet.UmlGraphDoc" path="${umlgraph.dir}/UmlGraph.jar" > <param name="-dotexecutable" value="${dot.dir}/dot" /> <param name="-all" /> <param name="-private" /> <param name="-horizontal" /> <param name="-nodefontclassname" value="Monaco"/> <param name="-nodefontclasssize" value="14"/> <param name="-nodefontname" value="Monaco"/> <param name="-nodefontsize" value="10" /> <param name="-nodefillcolor" value="mistyrose" /> </doclet> </javadoc> <apply executable="${dot.dir}/dot" dest="${reports.dir}" parallel="false"> <arg value="-Tpng"/> <arg value="-o"/> <arg value="-Gratio=0.7"/> <arg value="-Eminlen=2"/> <targetfile/> <srcfile/> <fileset dir="${reports.dir}" includes="*.dot"/> <mapper type="glob" from="*.dot" to="*.png"/> </apply> </target>

Thanks for answer.

Comment viewing options

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