Fabrizio Giudici is a Senior Java Architect with a long Java experience in the industrial field. He runs Tidalwave, his own consultancy company, and has contributed to Java success stories in a number of fields, including Formula One. Fabrizio often appears as a speaker at international Java conferences such as JavaOne and Devoxx and is member of JUG Milano and the NetBeans Dream Team. Fabrizio is a DZone MVB and is not an employee of DZone and has posted 67 posts at DZone. You can read more from them at their website. View Full User Profile

A Better Way for UML Management

09.03.2008
| 5699 views |
  • submit to reddit

While aiming at blueMarine 1.0 for the end of the year, the effort is being put not only to stability and performance, but also on cleaning up the APIs in order to have a polished and stable version that others might use.

To that end, I'm finding an excellent tool in the book "Practical API Design: Confessions of a Java Framework Architect" by Jaroslav Tulach (I've not finished it yet, I'll post a review as soon as I complete reading it), but my concern is also to write the proper documentation for users. One of the problems is with the UML diagrams - so far I've used the UML editor in NetBeans, but keeping them up-to-date is really time expensive, especially after some heavy refactoring.

Meera Subbarao and Geertjan Wielenga have written about a better solution (start reading this article on DZone): using a custom Javadoc doclet (UmlGraphDoc) to automatically generate the UML diagrams and put there in the generated javadocs (of course, you can even take the diagrams alone and reuse them on other documents). They explained the process in details with some examples about customizing build.xml, here I'm adding how the customization looks for a NetBeans RCP module; you just need to add this target to your script:

    <target name="-javadoc-with-packages" depends="build-init,-javadoc-init,netbeans" if="module.javadoc.packages">
<mkdir dir="${netbeans.javadoc.dir}/${code.name.base.dashes}"/>
<javadoc destdir="${netbeans.javadoc.dir}/${code.name.base.dashes}"
packagenames="${module.javadoc.packages}"
source="${javac.source}"
windowtitle="${javadoc.title}"
failonerror="false"
encoding="UTF-8">
<classpath refid="cp"/>
<sourcepath location="${src.dir}"/>
<doctitle>${javadoc.title}</doctitle>
<header>${javadoc.header}</header>
<doclet name="org.umlgraph.doclet.UmlGraphDoc"
path="${tools.dir}/UmlGraph-5.1/UmlGraph.jar">
<param name="-attributes" />
<param name="-operations" />
<param name="-qualify" />
<param name="-types" />
<param name="-visibility" />
<param name="-inferdep" />
<param name="-inferrel" />
<param name="-inferdepinpackage" />
</doclet>
</javadoc>
<apply executable="dot" dest="." parallel="false">
<arg value="-Tpng"/>
<arg value="-o"/>
<targetfile/>
<srcfile/>
<fileset dir="." includes="*.dot"/>
<mapper type="glob" from="*.dot" to="*.png"/>
</apply>
</target>

at this point, launching ant javadoc as usual will do the job, as the described target will just replace the one in the NetBeans RCP harness.

You can find a diagram example in context in the blueMarine javadocs and an inline example below. I'm pretty pleased with it, I just need to understand how to improve the layout - my packages have just a few classes (as it should be) and usually a few methods, but some get large boxes because of the signature of some method; also in some cases UmlGraphDoc includes in my diagram the whole description of some common classes such as String, but this is just something I can work on later. Much better than doing it by hand. BTW, Geertjan said that he will talk also about how to automatically generate a dependency diagram of the various modules in a NetBeans RCP application; also because, as Meera explained, you can put this stuff into Hudson and have the documentation automatically generate and published. Always up to date!

 

 

From http://weblogs.java.net/blog/fabriziogiudici/

AttachmentSize
it.tidalwave.bluemarine.preview.png73.52 KB
Published at DZone with permission of Fabrizio Giudici, author and DZone MVB.

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

Comments

Meera Subbarao replied on Wed, 2008/09/03 - 10:05am

Interesting article, Fabrizio. 

Diomidis Spinellis replied on Sat, 2008/09/06 - 1:26am

  • You can use the -hide parameter to hide classes you don't want.
  • You can generate more compact diagrams by omitting the -type parameter.
  • You don't neet to call the dot executable.  UmlGraphDoc will do it for you.

Geertjan Wielenga replied on Fri, 2008/09/05 - 4:00pm

How does your approach differ to mine here:

http://blogs.sun.com/geertjan/entry/generate_uml_diagrams_into_javadoc

Also, it would be cool if the target could be set on the suite and then all Javadoc for all modules would be created, so that the new target would be added in the suite's build.xml only, and not in each of the potentially many modules within it. Do you have any thoughts on that?

Fabrizio Giudici replied on Sun, 2008/09/07 - 10:39am

Thank you Diomidis, it's really a neat tool.

Geertjan, my approach is of course very similar to yours (99%), there are only a few differences in some details of the -javadoc-with-packages script that is for RCP projects and not J2SE ones. The fact that the target name starts with a dash makes it understand that it isn't something that you call directly, but it's called by the harness when you run ant-javadoc in a module project.

For generating all the javadocs in a suite, I put this in the build.xml of the suite project:

    <target name="javadoc" depends="-init">
        <subant target="javadoc" buildpath="${modules.sorted}" inheritrefs="true" inheritall="false">
            <property name="netbeans.javadoc.dir" value="${basedir}/build/javadoc"/>
        </subant>
    </target>

And that's over :-) Actually since Meera and you published that stuff, all blueMarine javadocs are updated with their UML diagrams on the website, thanks to Hudson.

Comment viewing options

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