Be a better Developer: Automatically generated Class Diagrams using Maven & UMLGraph

Drawing Class Diagrams preemptive is sometimes nice to optimize your thought of design. But it will still most likely change in the development phase. Since your Class Diagram is part of your documentation it should be up to date all the time. There is no point in having a Class Diagram if the code does not fit it. You could keep adapting the changes to the Class Diagram by hand, but that can get very time-consuming and exhausting. You should rather automate that process, and there are several ways to achieve exactly that. You could for example search for a UML Class Diagram Tool supporting roundtrip engineering. There are some commercial, and even some free ones available. Not all of them work very well and it can be a frustrating task to figure out which way to go. You would probably try out some and throw them away because they are just not what you expected.
Thats why i want to show you a different approach: Letting a Javadoc Doclet draw the Class Diagrams in build phase and embed them into your javadoc automatically. UMLGraph is such a doclet. It analyzes your code, draws Class Diagrams automatically and embed them into your javadoc.

Since maven can run javadoc at build phase it's perfect. You just have to configurate the maven-javadoc-plugin to use UMLGraph.

Configurate Maven to use UMLGraph

<reporting>                                                                              
    <plugins>                                                                            
        <plugin>                                                                         
            <groupId>org.apache.maven.plugins</groupId>                                  
            <artifactId>maven-javadoc-plugin</artifactId>                                
            <version>2.9</version>                                                       
            <configuration>                                                              
                <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>                         
                <docletArtifact>                                                         
                    <groupId>org.umlgraph</groupId>                                      
                    <artifactId>umlgraph</artifactId>                                    
                    <version>5.6</version>                                               
                </docletArtifact>                                                        
                <additionalparam>-views -all</additionalparam>                           
                <useStandardDocletOptions>true</useStandardDocletOptions>                
            </configuration>                                                             
        </plugin>                                                                        
    </plugins>                                                                           
</reporting>

Beware that the javadoc doclet api has changed from jdk 1.6 to jdk 1.7 and most of the online tutorials are outdated because of that. UMLGraph adapted to jdk 1.7 since version 5.5.

If we run mvn site right now, we will just get that error:
java.io.IOException: Cannot run program "dot": java.io.IOException: error=2, No such file or directory
This means that the program dot was not found which is a part of the graphviz library.

Install Graphviz

For UMLGraph to run you need graphviz installed. Go to the Download Page, and choose your package. On linux you could even sudo aptget install graphviz. Beware that you might have to reboot or relogin to use graphviz, because the Systems Path is extended during installation.

First Result

Run mvn site, and open target/site/apidocs/index.html afterwards.

As you can see its drawing beautiful and accurate UML Class Diagrams.

Custom Configuration

If you dont want attributes/methods or other extras you are totally free to configurate those graphs. See Class Diagram Options. Just add them to the

<additionalparam>-views -all</additionalparam>

tag in pom.xml

3 comments:

greyfairerMarch 25, 2013 at 4:01 PM
If you like this, also take a look at plantuml.

PlantUML allows to create a diagram in pseudo-code. You have a number of ways to generate the actual images from it, including the maven site plugin or in javadoc:

http://plantuml.sourceforge.net/javadoc.html

The advantage of this is that you can write the UML in your IDE and include it in your sources, you don't need to switch to a different environment. And if you IDE can detect class names in text files during refactorings, it will also follow class renames in your plantUML files.
Tarun TelangMay 22, 2013 at 7:19 PM
Great way to document your source code. I would like to try this in languages other than Java.