The UMLJGraph Logo

Introduction

UMLJGraph is inspired by the UMLGraph Javadoc Doclet, written by Diomidis Spinellis. The UMLGraph Doclet writes graph description files in the Graphviz' dot format. Unfortunately the Graphviz package is a native application and does not integrate smoothly into a Java tool chain. It gets extra hard when you try to run Graphviz on a platform where no binary packages for Graphviz are available.

This project provides a pure Java solution for the problem of creating UML diagrams from annotated Java sources. Because of the pure Java solution it integrates smoothly into a Java tool chain. This integration becomes even smoother by using the Ant taskdefs, provided by this project. The project contains the following tools:

  1. XmiDoclet to create XMI files from Java sources
  2. XmiConvert application for XMI to SVG/PNG/JPG conversion
  3. UML Extension Library for JGraph (Cells, Views, Renderers)
  4. Ant taskdefs: umldiagram

These tools can be used to create UML diagrams from annotated Java source files. To achieve this, XMI files are created by the XmiDoclet, then the UML classes and relations are converted into a JGraph representation and rendered either into a SVGGraphics2D (Batik) for SVG output or into a normal Graphics2D for PNG and JPG export.

This project is work in progress. A lot of things have to be tweaked and fixed in order to call this a stable project. See the TODO file on what still needs to be done.

News

XmiDoclet

The XmiDoclet uses the MOF Repository implementation from NetBeans, called MetaData Repository, together with the uml2mof tool which provides an UML 1.4 API instance.

The XMI UML meta-model does not include any layout specific tags. That means that the generated XMI files contain the classes and their relationships only. They do not contain any information how the diagrams should look like. This kind of information is ususally stored in the <XMI:extension> element. But as the name indicates this is an extension tag and thus its hierarchy not defined by the XMI specification.

The XmiDoclet can be used stand-alone, as shown in the Ant build.xml fragment below.

   <path id="xmidoclet.classpath">
      <pathelement location="build/xmidoclet.jar"/>
      <pathelement location="lib/mdr/mdr.jar" />
      <pathelement location="lib/mdr/jmi.jar" />
      <pathelement location="lib/mdr/jmiutils.jar" />
      <pathelement location="lib/mdr/mof.jar" />
      <pathelement location="lib/mdr/mdrapi.jar" />
      <pathelement location="lib/mdr/openide-util.jar" />
      <pathelement location="lib/uml2mof/uml-1.4.jar" />
   </path>

   <target name="xmidoclet">
      <mkdir dir="build/xmidoclet"/>
      <javadoc
         packagenames="net.sourceforge.umljgraph.*"
         destdir="build/xmidoclet">

         <doclet name="net.sourceforge.umljgraph.xmi.doclet.XmiDoclet"
                 pathref="xmidoclet.classpath">
            <param name="-d" value="build/xmi/doclet"/>
            <param name="-n" value="test"/>
         </doclet>

         <sourcepath>
            <pathelement path="test/java"/>
         </sourcepath>
      </javadoc>
   </target>

The fragment above creates a build/xmidoclet/test.xmi file which contains all classes from the test/java folder. To restrict the classes that go into the XMI file you need to specify a tighter <sourcepath> <fileset>.

You can easily check the generated XMI file by loading it into a XMI compliant UML modeling tool, for example Umbrello. In order to see how Umbrello stores layout information just drag a few classes into the diagram area and store the XMI file again. When opening it with a text editor you can see Umbrello's layout extensions in the <XMI:extension> tag.

XmiConvert

The XmiConvert tool can be used to convert a XMI file, containing classes and their relationships, into PNG and JPG bitmaps and into a SVG vector image.

        # java -jar lib/xmiconvert.jar --help
        Usage: XmiConvert [-f|-d] <XmiFile>
            -f|--format FMT1[,FMTn[,...]]    FMTx : 'SVG|PNG|JPG'
            -d|--outdir <FOLDER>             The ouput folder
            -v|--verbose                     Enable verbose output
            -h|--help                        Show this usage info

XmiConvert is primarily used to render XMI files generated by the XmiDoclet. Therefore it does not provide rendering only part of an XMI file. This might be added in a later release, or when someone decides to contribute such an extension.

For standalone testing you can create an UML diagram with your favorite tool, for example Umbrello and save it as XMI. Then use the following command to create PNG, JPG, and SVG from the XMI file: java -jar lib/xmiconvert.jar umbrello.xmi

Ant taskdefs

TODO

UML Extension Library for JGraph

The basis for this library has been laid out by Jack Hong who has started JRoseViewer, a viewer application for Rational Rose model files. Because of of a two years inactivity of the JRoseViewer project the Cells and Views did not compile with the latest JGraph version anymore. Fixes for these issues together with a few rendering fixes are now packaged in a separate jar file, coming with this project, so that UML graphs can be built with JGraph and this extension library in a standalone mode.

See the HelloWorld example on how the library can be used. For an example on how to automatically layout an UML diagram, see the Layout example.

Known Issues

Unfortunately the layout algorithms that come with the JGraph Addons package are not well maintained. They are basically working but no bug-fixes or improvements are done anymore. I tested quite a few different layout algorithms for UMLJGraph. The best one seems to be the SugiyamaLayoutAlgorithm. Although the arrows are not laid out from the bottom to the top, which is the usual way to display UML class diagrams. This special layout can be achieved with the TreeLayoutAlgorithm with orientation set to SOUTH, but with the TreeLayoutAlgorithm you get overlapping classes as soon as you have more than one root node.

Resources

References

(c) Copyright 2005, Michael Rumpf
Last modified: $Date: 2005/08/19 10:49:32 $