Frequently Asked Questions

Contents

What is the command line sequence to generate a UMLGraph class diagram?

Assuming that you diagram's description is in the file Diag.java, issue the command:
java -jar path-to/UmlGraph.jar -package -output - Diag.java | dot -Tpng -oDiag.png Diag.dot
or
javadoc -docletpath path-to/UmlGraph.jar -package -doclet gr.spinellis.umlgraph.doclet.UmlGraph -output Diag.dot Diag.java
dot -Tpng -oDiag.png Diag.dot
In the above you can change png to another file format, and add more UMLGraph switches before the -option switch.

Note that the first format requires the file tools.jar to be in the same directory as UmlGraph.jar.

Why are the SVG diagrams dot generates malformed?

UMLGraph uses guillemot characters for representing the angle brackets around stereotypes, as in «interface». By default these are encoded as ISO-8859-1 characters, which are illegal in the UTF-8 output that dot generates for SVG. When using dot to generate SVG output, you should also specify -outputencoding utf8 to UMLGraph.

How can I improve the quality of the bitmap images I generate?

Both dot and pic2plot can directly produce bitmap images in formats like GIF, PNG and PNM. However, if you want to produce presentation-quality output the a vector output format like Postscript or SVG is preferable. If you do require a bitmap format, it might be worth to create it at a higher resolution from a Postscript image, and then downsample it. This procedure (used for the diagrams appearing on the UMLGraph web site) will create an antialiased image of a higher quality than what the default bitmap output options produce. The following pipeline is an example of how you can achieve this effect:
dot -Tps FILENAME.dot |
gs -q -r360 -dNOPAUSE -sDEVICE=pnm -sOutputFile=-  - -c quit |
pnmcrop |
pnmscale 0.25 |
ppmtogif >FILENAME.gif
(David Griffiths reports that he had to add to the gs command -sPAPERSIZE=a4 or -dDEVICEHEIGHTPOINTS=1000 to avoid getting his results chopped-off.)

One other possibility for converting the sequence diagram into Postscript is to pass it through pic and groff. Tools like ps2epsi and ps2eps can then be used to convert the Postscript into encapsulated Postscript. Of course, groff users will just use the pic program as part of their processing pipeline.

How can I improve the layout of my class diagrams?

Try manipulating the dot parameters ratio, minlen, ranksep, and nodesep. For example, Arnaud Rogues recommends running dot with command-line arguments as follows.
dot -Gratio=0.7 -Eminlen=2

A class appears multiple times in a class diagram. Why?

Most probably your class diagram uses packages, and you are not qualifying the classes with the respective package names in the tags you use. The tags are not smart enough to do the package resolution, so you will have to prepend the package name to the class, or avoid using packages.

Problematic Specification

package test;
abstract class AbstractNode {}
/** @composed 1 has * AbstractNode */
class InnerNode extends AbstractNode {}
class Leaf extends AbstractNode {}

First Approach: Class Name Qualified with the Package

package test;
abstract class AbstractNode {}
/** @composed 1 has * test.AbstractNode */
class InnerNode extends AbstractNode {}
class Leaf extends AbstractNode {}

Second Approach: No Package Specification

abstract class AbstractNode {}
/** @composed 1 has * test.AbstractNode */
class InnerNode extends AbstractNode {}
class Leaf extends AbstractNode {}

Shouldn't static fields appear underlined?

Yes they should. Unfortunately, dot does not (yet) support a way to underline single labels, and thus UMLGraph can not show the static fields underlined.

Where can I find a pic2plot executable for Windows?

A port of pic2plot for Windows can be found in GNU PlotUtils, which is part of the GnuWin32 project.

Under Windows the output of pic2plot appears empty. Why?

On Windows platforms note that the current version of pic2plot appears to be very picky about carriage return (CR - \r) characters (by default, CR is part of the platform's end of line sequence) appearing in its input file. Therefore, you will probably want to instruct your editor to create Unix-style files, or filter the files to remove the carriage return characters. The following Perl invocation is such a filter:
perl -p -e "BEGIN {binmode(STDOUT);} s/\r//"
In addition, pic2plot appears to require that the last input file be properly terminated (with a newline). Apparently, some Windows editors may leave the last line unterminated, so if your editor is in this category it may be safer to add a blank line in the end.

I have a problem with Maven's Dotuml plugin. Can you help me?

Sorry, I did not develop this plugin, and therefore can not offer help. Have a look at the project's documentation and mailing lists available through plugin web page.

How can I make the UMLGraph doclet generate sequence diagrams?

You can't. You have to write the pic code for the sequence diagrams by hand.

Why the vanity package name? Why not name the package org.umlgraph?

The package names are supposed to be unique. If everybody names their project under the org.* namespace there's no mechanism for ensuring that the name will be unique, unless the developer also registers the corresponding domain name. Registering a different domain name for each project is not practical, therefore I name the packages I develop using the domain name I own.

Why do the options specified in the UMLOptions class stop working, when I pass the packagenames option to javadoc?

When you pass the packagenames option to javadoc, the default (unnamed) package (and the UMLOptions class located in it) is ignored. In such cases you should include the UMLOptions class within a named package.

Why doesn't UMLGraph run under Mac OS X?

Make sure you are running Java 1.5 (run java -version to see). If you are not running 1.5 you may need to adjust the symbolic links in /System/Library/Frameworks/JavaVM.framework/Versions.

Can I create UML class diagrams from C++ code?

This blog entry describes a simple solution that has worked for me. Depending on your requirements YMMV.

How can I get around a UMLGraphDoc crash with a ClassCastException?

This happens due to a know javadoc bug. By fixing the classpath used for the UNLGraph invocation you can avoid this problem. Olivier Duysens notes:
JBuilder users need to go to Preferences/Build/Ant, and tick the box "Use project libraries when running ant" to solve the issue.

Under what license is UMLGraph distributed?

UMLGraph is distributed under the BSD license (see the file LICENSE in the distribution). For uniformity with the rest of the web content appearing on this site, the web site of UMLGraph appears under a Creative Commons Attribution-NonCommercial-NoDerivs 2.5 license. This affects only the UMLGraph home page; all other material (for example the documentation) is also part of the UMLGraph distribution, and can therefore be used under the BSD license.

Why do I get an exception java.lang.NoClassDefFoundError: com/sun/tools/javadoc/Main?

This exception will occur when you execute UMLGraph directly as a jar (not throughjavadoc), and the files UmlGraph.jar and tools.jar are not in the same directory. Either copy UmlGraph.jar in the directory where the tools.jar of the JDK distribution is located (and execute UmlGraph.jar from there), or copy tools.jar to the directory where UmlGraph.jar is located. (The file tools.jar is typically located in the lib directory of your JDK distribution.)