UMLGraph dds

UMLGraph - Declarative Drawing of UML diagrams

UMLGraph allows the declarative specification and drawing of a number of UML diagrams. You specify your design using the Java syntax complemented by javadoc tags. Running the UmlGraph doclet on your specification will generate a Graphviz diagram specification that can be automatically processed to create Postscript, GIF, SVG, JPEG, fig, or Framemaker drawings.

The following is an example of a specification and the resulting UML diagram: 
class Person {
	String Name;
}

class Employee extends Person {}

class Client extends Person {}

See also Diomidis Spinellis. On the declarative specification of models. IEEE Software, 20(2):94-96, March/April 2003.

Operation

To use UMLGraph you need to have javadoc and Graphviz installed on your computer. Both programs are freely available, from Sun and AT&T respectively, for many platforms including Unix and Windows. 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 is not designed for this purpose; the resulting graphs may be large and unwieldy.

UMLGraph is implemented as a javadoc doclet (a program satisfying the doclet API that specifies the content and format of the output generated by the javadoc tool). Javadoc is part of the Sun JDK, so a typical JDK installation will also include javadoc. Before running javadoc you need to place the UmlGraph.jar file in a location accessible by javadoc (e.g. the Java class path or the current directory). You then run javadoc with arguments -doclet UmlGraph -docletpath /path/to/UmlGraph.jar and append at the end the file(s) that contain your diagram specification. You can of course use any of the javadoc general options; -private is usually needed to avoid having to explicitly specify public elements. Example: 

javadoc -docletpath UmlGraph.jar -doclet UmlGraph -private Simple.java
javadoc will create a file named graph.dot in the current directory; this is a text file that can be processed by the Graphviz dot program to layout and draw the graph. A command line like the following will convert the graph.dot file into Postscript: 
dot -Tps -ograph.ps graph.dot
Refer to the dot documentation for information on creating other file formats or adjusting the UMLGraph output.

Modelling

UMLGraph allows you to model All relationship tags appart from @extends take four arguments:
  1. The source adornments (role, multiplicity, and visibility)
  2. The relationship name
  3. The target adornments (role, multiplicity, and visibility)
  4. The target class
Arguments can be space-separated, or enclosed in quotes if they need to contain the space character. The - character is used as a placeholder to denote empty arguments. You can use the \n sequence to separate the first three adornments in separate centered lines; the \l and \r sequences can also be used to generate left and right aligned lines. You can use the < and > characters in the relationship name to enclose stereotype names. These will be automatically enclosed in guillemots. Note that a relationship's target class is not implicitly defined; it should also be specified using the Java class syntax. The following is an example of a relationship specification and the resulting UML diagram: 
class Tyre {}
class Engine {}
class Body {}

/**
 * @composed 1 - 4 Tyre
 * @composed 1 - 1 Engine
 * @composed 1 - 1 Body
 */
class Car {}

Program Options

A number of command-line options contol the operation of UMLGraph:
-qualify
Produce fully-qualified class names.
-horizontal
Layout the graph in the horizontal direction.
-attributes
Show class attributes (Java fields)
-operations
Show class operations (Java methods)
-visibility
Adorn class elements according to their visibility (private, public, protected)
-types
Add type information to attributes and operations
-all
Same as -attributes -operations -visibility -types
-nodefillcolor
Specify the color to use to fill the shapes.
-nodefontname
Specify the font name to use inside nodes.
-nodefontabstractname
Specify the font name to use inside abstract class nodes.
-nodefontsize
Specify the font size to use inside nodes.
-nodefontcolor
Specify the font color to use inside nodes.
-edgefontname
Specify the font name to use for edge labels.
-edgefontsize
Specify the font size to use for edge labels.
-edgefontcolor
Specify the font color to use for edge labels.
-edgecolor
Specify the color for drawing edges.
-bgcolor
Specify the graph's background color.

All colors can be either a symbolic name (e.g. blue), a tripple specifying hue-saturation-brightness as values 0-1 (e.g. ".13 0.9 1"), or a tripple specifying red-green-blue values as hexadecimal digits prefixed by a # (e.g. "#ff8020"). The symbolic color names are derived from the X Windows System; you can find a complete list in the Graphviz documentation.

Font names are passed directly to the dot graph generation back-end. In general the Postcript standard names Times, Helvetica, Courier, and Symbol are safe to use.

Since the options are really a part of the generated graph you want in many cases to include them in the diagram specification. You can do that by adding javadoc @opt tags in front of a class named UMLOptions, as in the following example: 

/** 
 * @opt horizontal 
 * @opt all 
 * @hidden
 */
class UMLOptions {}
You can also change the UMLGraph operation on a per-class basis by using @opt attributes on individual classes. In this case the @opt specification temporarily overrides the particular global setting for the class being processed.

Availability

UMLGraph is hereby made freely available as Open Source Software. You can download it in source and compiled format from the following links:

Version History

Version 1.20 2002/09/23
Fixed bug in 1.19 with node font name specification.
Version 1.20 2003/04/25
Fixes by Nick Efthymiou (thanks): will generate SVG hyperlinks to Javadoc documentation, better handling of abstract class fonts, and correct listing of interfaces.
Version 1.19 2002/09/20
New options: nodefontname, nodefontabstractname, nodefontsize, nodefontcolor, edgefontname, edgefontsize, edgefontcolor, edgecolor, bgcolor.
Version 1.18 2002/08/26
Version 1.15 2002/07/26
First public release.

More Examples

Generalisation Relationships

/*
 * Generalisation
 * UML User Guide p. 141
 */

/* Basic categorisations */
class Asset {}
class InterestBearingItem {}
class InsurableItem {}

/* Asset types */
/** 
 * @extends InsurableItem 
 * @extends InterestBearingItem 
 */
class BankAccount extends Asset {}
/** @extends InsurableItem */
class RealEstate extends Asset {}
class Security extends Asset {}

/* Securities */
class Stock extends Security {}
class Bond extends Security {}

/* Bank accounts */
class CheckingAccount extends BankAccount {}
class SavingsAccount extends BankAccount {}
Download the declarative specification, the generated dot code.

Advanced Relationships

/*
 * Advanced relationships
 * UML User Guide p. 137
 */

/** 
 * @opt attributes 
 * @opt operations 
 * @hidden
 */
class UMLOptions {}

class Controller {}
class EmbeddedAgent {}
class PowerManager {}

/**
 * @extends Controller
 * @extends EmbeddedAgent
 * @navassoc - - - PowerManager
 */
class  SetTopController implements URLStreamHandler {
	int authorizationLevel;
	void startUp() {}
	void shutDown() {}
	void connect() {}
}

/** @depend -  - SetTopController */
class ChannelIterator {}

interface URLStreamHandler {
	void OpenConnection();
	void parseURL();
	void setURL();
	void toExternalForm();
}
Download the declarative specification, the generated dot code.

Schema

/*
 * Schema model
 * UML User Guide p. 112
 */

/** 
 * @opt operations 
 * @opt attributes 
 * @opt types 
 * @hidden
 */
class UMLOptions {}

/* Define some types we use */
/** @hidden */
class Name {}
/** @hidden */
class Number {}

/**
 * @has 1..* Member * Student
 * @composed 1..* Has 1..* Department
 */
class School {
	Name name;
	String address;
	Number phone;
	void addStudent() {}
	void removeStudent() {}
	void getStudent() {}
	void getAllStudents() {}
	void addDepartment() {}
	void removeDepartment() {}
	void getDepartment() {}
	void getAllDepartments() {}
}

/**
 * @has 1..* AssignedTo 1..* Instructor
 * @assoc 1..* - 1..* Course
 * @assoc 0..* - "0..1 chairperson" Instructor
 */
class Department {
	Name name;
	void addInstructor() {}
	void removeInstructor() {}
	void getInstructor() {}
	void getAllInstructors() {}
}

/**
 * @assoc * Attends * Course
 */
class Student {
	Name name;
	Number studentID;
}

class Course {
	Name name;
	Number courseID;
}

/**
 * @assoc 1..* Teaches * Course
 */
class Instructor {
	Name name;
}
Download the declarative specification, the generated dot code.

Element Visibility

/**
 * Attribute and operation visility
 * UML User Guide p. 123
 *
 * @opt operations 
 * @opt attributes 
 * @opt types 
 * @opt visibility 
 * @hidden
 */
class UMLOptions {}

/** @hidden */
class Tool {}

class Toolbar {
	protected Tool currentSelection;
	protected Integer toolCount;
	public void pickItem(Integer i) {}
	public void addTool(Tool t) {}
	public void removeTool(Integer i) {}
	public Tool getTool() {}
	protected void checkOrphans() {}
	private void compact() {}
}
Download the declarative specification, the generated dot code.

Association Types

/** 
 * Associations with visibility
 * UML User Guide p. 145
 *
 * @opt horizontal 
 * @hidden
 */
class UMLOptions {}

/** @assoc * - "*\n\n+user " User */
class UserGroup {}

/** @navassoc "1\n\n+owner\r" - "*\n\n+key" Password */
class User{}

class Password{}
Download the declarative specification, the generated dot code.

Real Example (Catalina Classes)

/*
 * Interface and generalization relationships in Jakarta Catalina
 */

class HttpResponseBase
	extends ResponseBase
	implements HttpResponse, HttpServletResponse {}

abstract class HttpResponseWrapper
	extends ResponseWrapper 
	implements HttpResponse {}

class HttpResponseFacade
	extends ResponseFacade 
	implements HttpServletResponse {}

abstract class ResponseWrapper implements Response {}
abstract interface HttpResponse extends Response {}
abstract class ResponseBase implements Response, ServletResponse {}
abstract interface HttpServletResponse {}
class ResponseFacade implements ServletResponse {}

abstract interface ServletResponse {}
abstract interface Response {}

Download the declarative specification, the generated dot code.

Class Stereotypes and Tagged Values

/*
 * Class stereotypes and tagged values
 * UML User Guide p. 439
 */

/** 
 * @opt attributes 
 * @opt operations 
 * @opt types 
 * @hidden
 */
class UMLOptions {}

/** @hidden */
class Action {}

/** 
 * @stereotype container 
 * @tagvalue version 3.2
 */
class ActionQueue {
	void add(Action a) {};
	/** @tagvalue version 1.0 */
	void add(Action a, int n) {};
	void remove(int n) {};
	/** @stereotype query */
	int length() {};
	/** @stereotype "helper functions" */
	void reorder() {};
}
Download the declarative specification, the generated dot code.

Colors, Global and Local Options

/**
 * @opt edgecolor "yellow"
 * @opt nodefontname "Times" 
 * @opt bgcolor ".7 .9 1" 
 * @opt nodefillcolor "#a0a0a0" 
 * @opt nodefontsize 14
 * @hidden
 */
class UMLOptions{}

/** 
 * @opt nodefontname "Helvetica-Bold" 
 * @opt nodefontcolor "white"
 * @composed - - - Red
 * @composed - - - Green
 * @composed - - - Blue
 * @opt attributes
 * @opt visibility
 * @opt types
 */
class Pixel {
	private int x, y;
	public void setColor(ColorValue v) {}
}

/** @opt nodefillcolor red */
class Red {}

/** @opt nodefillcolor green */
class Green {}

/** @opt nodefillcolor blue */
class Blue {}

/** @hidden */
class ColorValue{}
Download the declarative specification, the generated dot code.

Diomidis Spinellis home page

$Id$
(C) Copyright 2002 Diomidis D. Spinellis. May be freely uploaded by WWW viewers and similar programs. All other rights reserved.