Class Diagram Operations

UMLGraph's input follows the Java syntax and semantics. However, since the main purpose of UMLGraph is the declarative specification of UML diagrams there is no need to flesh-out each class's methods, to completely specify each class, or to specify package information. You only specify the details you want to appear on the graph. If you wish your (Java) implementation to evolve together with the design feel free to include code or additional details. You can hide these details from the UML diagram using the javadoc @hidden tag applied to classes, methods, and fields. In theory you can also use UMLGraph to reverse engineer existing Java code. Note however that UMLGraph was not originally designed for this purpose; the resulting graphs may be large and unwieldy.

There are various ways to invoke UMLGraph, each providing a different balance between convenience and flexibility.

Option 1: Using the Supplied Script

This is the simplest option. If umlgraph (or umlgraph.bat) is correctly installed, you can run UMLGraph by simply specifying the basename of the Java file containing the diagram specification and the file type of the generated diagram (e.g. gif, ps, png, svg). Example:

umlgraph Test png

Any additional UMLGraph or javadoc arguments can be added at the end of the command line. This command will read the specification file (e.g. Test.java) and generate directly a diagram of the appropriate type (e.g. Test.png).

Option 2: Running Java

This option provides the maximum flexibility. In order to run, javadoc needs to access tools.jar. You can accomplish this in two ways.

Specify the location of tools.jar as a part of Java's classpath and specify the full name of the UMLGraph doclet as an argument to Java. This is an invocation example under Windows
java -classpath "lib/UmlGraph.jar;c:\program files\java\jdk1.6.0_02\lib\Tools.jar"
org.umlgraph.doclet.UmlGraph -package Test.java

and under Unix
java -classpath '/usr/share/lib/UmlGraph.jar:/opt/Java-1.6/lib/tools.jar' \
org.umlgraph.doclet.UmlGraph -package Test.java
Place the UmlGraph.jar file in a directory that also contains the Java SDK tools.jar file. You can accomplish this either by copying UmlGraph.jar to the SDK lib directory where tools.jar resides, or by copying the JDK tools.jar file into the directory where you installed UMLGraph. You then run
java -jar /path/to/UmlGraph.jar yourfile1.java ...

You can use any of the javadoc general options; -private is usually needed to avoid having to explicitly specify public elements. Example:

java -jar /usr/jvm/java-1.5.0/lib/UmlGraph.jar -private Simple.java

To generate a diagram of all classes in the package specify as arguments to the Java invocation the name of the package and the directory where it resides. The following example generates a diagram of all UMLGraph classes.

java -classpath ... org.umlgraph.doclet.UmlGraph -sourcepath src/main/java org.umlgraph.doclet

Specifying some packages before the list of source files will designate those packages as local. When you specify a package list, the SVG output UMLgraph generates will contain local hyperlinks for the local classes and hyperlinks to the Sun Java API documentation for all other classes.

Option 3: Running Javadoc

Alternatively, you can also run UMLGraph from within javadoc. This can be useful if your IDE provides additional support for running javadoc. In this case you run javadoc with arguments -doclet org.umlgraph.doclet.UmlGraph -docletpath /path/to/UmlGraph.jar and append at the end the file(s) that contain your diagram specification. Example:

javadoc -docletpath UmlGraph.jar -doclet org.umlgraph.doclet.UmlGraph -private Simple.java

Running Dot

The last two options, will generate the UML diagram in Graphviz dot format. This is a text file that can be processed by the Graphviz dot program to layout and draw the graph. javadoc will create by default a file named graph.dot in the current directory. A command line like the following will convert the graph.dot file into Postscript:

dot -Tps -ograph.ps graph.dot

or PNG

dot -Tpng -ograph.png graph.dot

Refer to the dot documentation for information on creating other file formats or adjusting the UMLGraph output.

You also can pipe the result of UMLGraph directly into dot:

java -jar /.../UmlGraph.jar -private -output - Simple.java | dot -Tgif -ograph.gif

Note that when you use dot for generating SVG diagrams your should specify the -outputencoding UTF-8 option to UMLGraph. This option will correctly render the stereotype guillemot characters in the dot output and the corresponding SVG file.