mirror of https://github.com/dspinellis/UMLGraph
591 lines
16 KiB
HTML
591 lines
16 KiB
HTML
<!doctype html public "-//IETF//DTD HTML//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>UMLGraph - Declarative Drawing of UML diagrams</TITLE>
|
|
<META NAME="AUTHOR" CONTENT="Diomidis Spinellis">
|
|
</HEAD>
|
|
<body>
|
|
<h1 align=right><tt><font color="#ff0000">UMLGraph dds</font></tt></h1>
|
|
<h2>UMLGraph - Declarative Drawing of UML diagrams</h2>
|
|
<!-- Introduction {{{1 -->
|
|
UMLGraph allows the declarative specification and drawing of
|
|
a number of UML diagrams.
|
|
You specify your design using the Java syntax complemented by
|
|
<a href="http://java.sun.com/j2se/javadoc/"><em>javadoc</em></a>
|
|
tags.
|
|
Running the UmlGraph doclet on your specification will generate
|
|
a
|
|
<a href="http://www.research.att.com/sw/tools/graphviz/">Graphviz</a>
|
|
diagram specification that can be automatically processed to
|
|
create Postscript, GIF, SVG, JPEG, fig, or Framemaker drawings.
|
|
<p>
|
|
The following is an example of a specification and the resulting UML
|
|
diagram:
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
class Person {
|
|
String Name;
|
|
}
|
|
|
|
class Employee extends Person {}
|
|
|
|
class Client extends Person {}
|
|
</pre>
|
|
</td><td>
|
|
<img src="simple.gif">
|
|
</tr></table>
|
|
<p>
|
|
<b>See also</b>
|
|
Diomidis Spinellis. On the Declarative Specification of Models.
|
|
<em>IEEE Software</em>, 20(2), March/April 2003. To appear.
|
|
|
|
<h3>Operation</h3> <!-- {{{1 -->
|
|
To use UMLGraph you need to have
|
|
<a href="http://java.sun.com/j2se/javadoc/"><em>javadoc</em></a>
|
|
and
|
|
<a href="http://www.research.att.com/sw/tools/graphviz/">Graphviz</a>
|
|
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 <em>javadoc</em>
|
|
<code>@hidden</code> 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.
|
|
<p>
|
|
UMLGraph is implemented as a <em>javadoc</em> doclet (a program satisfying the
|
|
doclet API that specifies the content and format of the output
|
|
generated by the <em>javadoc</em> tool).
|
|
<em>Javadoc</em> is part of the Sun JDK, so a typical JDK installation will also
|
|
include <em>javadoc</em>.
|
|
Before running <em>javadoc</em> you need to place the <code>UmlGraph.jar</code>
|
|
file in a location accessible by <em>javadoc</em>
|
|
(e.g. the Java class path or the current directory).
|
|
You then run <em>javadoc</em> with arguments <code>-doclet UmlGraph</code>
|
|
<code>-docletpath /path/to/UmlGraph.jar</code>
|
|
and append at the end the file(s) that contain your diagram
|
|
specification.
|
|
You can of course use any of the <em>javadoc</em> general options;
|
|
<code>-private</code> is usually needed to avoid having to explicitly
|
|
specify public elements.
|
|
Example:
|
|
<pre>
|
|
javadoc -docletpath UmlGraph.jar -doclet UmlGraph -private Simple.java
|
|
</pre>
|
|
<em>javadoc</em> will create a file named <code>graph.dot</code>
|
|
in the current directory;
|
|
this is a text file that can be processed by the <em>Graphviz</em>
|
|
<em>dot</em> program to layout and draw the graph.
|
|
A command line like the following will convert the <code>graph.dot</code>
|
|
file into Postscript:
|
|
<pre>
|
|
dot -Tps -ograph.ps graph.dot
|
|
</pre>
|
|
Refer to the <em>dot</em> documentation for information on creating other file formats
|
|
or adjusting the UMLGraph output.
|
|
<h3>Modelling</h3> <!-- {{{1 -->
|
|
UMLGraph allows you to model
|
|
<ul>
|
|
<li>classes (specified as Java classes)
|
|
<li>attributes (specified as Java fields)
|
|
<li>operations (specified as Java methods)
|
|
<li>stereotypes (using the <code>@stereotype</code> <em>name</em> tag)
|
|
<li>tagged values (using the <code>@tagvalue</code> <em>name</em> <em>value</em> tag)
|
|
<li>implementation relationships (specified using the Java <code>implements</code> declaration)
|
|
<li>generalization relationships (specified using the Java <code>extends</code> declaration or (for multiple inheritance) the <em>javadoc</em> <code>@extends</code> tag)
|
|
<li>association relationships (specified using the <em>javadoc</em> <code>@assoc</code> tag)
|
|
<li>navigatable (directed) association relationships (specified using the <em>javadoc</em> <code>@navassoc</code> tag)
|
|
<li>aggregation relationships (specified using the <em>javadoc</em> <code>@has</code> tag)
|
|
<li>composition relationships (specified using the <em>javadoc</em> <code>@composed</code> tag)
|
|
<li>dependency relationships (specified using the <em>javadoc</em> <code>@depend</code> tag)
|
|
</ul>
|
|
All relationship tags appart from <code>@extends</code> take four arguments:
|
|
<ol>
|
|
<li> The source adornments (role, multiplicity, and visibility)
|
|
<li> The relationship name
|
|
<li> The target adornments (role, multiplicity, and visibility)
|
|
<li> The target class
|
|
</ol>
|
|
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:
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
class Tyre {}
|
|
class Engine {}
|
|
class Body {}
|
|
|
|
/**
|
|
* @composed 1 - 4 Tyre
|
|
* @composed 1 - 1 Engine
|
|
* @composed 1 - 1 Body
|
|
*/
|
|
class Car {}
|
|
</pre>
|
|
</td><td>
|
|
<img src="car.gif">
|
|
</tr></table>
|
|
|
|
<h3>Program Options</h3> <!-- {{{1 -->
|
|
A number of command-line options contol the operation of UMLGraph:
|
|
<dl>
|
|
<dt>-qualify<dd>Produce fully-qualified class names.
|
|
<dt>-horizontal<dd>Layout the graph in the horizontal direction.
|
|
<dt>-attributes<dd>Show class attributes (Java fields)
|
|
<dt>-operations<dd>Show class operations (Java methods)
|
|
<dt>-visibility<dd>Adorn class elements according to their
|
|
visibility (private, public, protected)
|
|
<dt>-types<dd>Add type information to attributes and operations
|
|
<dt>-all<dd>Same as
|
|
<code>-attributes</code>
|
|
<code>-operations</code>
|
|
<code>-visibility</code>
|
|
<code>-types</code>
|
|
<dt>-nodefillcolor<dd>Specify the color to use to fill the shapes.
|
|
<dt>-nodefontname<dd>Specify the font name to use inside nodes.
|
|
<dt>-nodefontabstractname<dd>Specify the font name to use
|
|
inside abstract class nodes.
|
|
<dt>-nodefontsize<dd>Specify the font size to use inside nodes.
|
|
<dt>-nodefontcolor<dd>Specify the font color to use inside nodes.
|
|
<dt>-edgefontname<dd>Specify the font name to use for edge labels.
|
|
<dt>-edgefontsize<dd>Specify the font size to use for edge labels.
|
|
<dt>-edgefontcolor<dd>Specify the font color to use for edge labels.
|
|
<dt>-edgecolor<dd>Specify the color for drawing edges.
|
|
<dt>-bgcolor<dd>Specify the graph's background color.
|
|
</dl>
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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 <em>javadoc</em> <code>@opt</code> tags in front
|
|
of a class named <code>UMLOptions</code>, as in the following example:
|
|
<pre>
|
|
/**
|
|
* @opt horizontal
|
|
* @opt all
|
|
* @hidden
|
|
*/
|
|
class UMLOptions {}
|
|
</pre>
|
|
|
|
You can also change the UMLGraph operation on a per-class basis by
|
|
using <code>@opt</code> attributes on individual classes.
|
|
In this case the <code>@opt</code> specification temporarily overrides
|
|
the particular global setting for the class being processed.
|
|
|
|
<h3>Availability</h3> <!-- {{{1 -->
|
|
UMLGraph is hereby made freely available as Open Source Software.
|
|
You can download it in source and compiled format from the following links:
|
|
<ul>
|
|
<li> <a href="UmlGraph.java">UmlGraph.java (source code)</a>
|
|
<li> <a href="UmlGraph.jar">UmlGraph.jar (compiled archive)</a>
|
|
<li> <a href="makefile">Makefile example (GNU make)</a>
|
|
</ul>
|
|
|
|
<h3>Version History</h3> <!-- {{{1 -->
|
|
<dl>
|
|
<dt>Version 1.20 2002/09/23<dd>
|
|
Fixed bug in 1.19 with node font name specification.
|
|
|
|
<dt>Version 1.19 2002/09/20<dd>
|
|
New options:
|
|
nodefontname,
|
|
nodefontabstractname,
|
|
nodefontsize,
|
|
nodefontcolor,
|
|
edgefontname,
|
|
edgefontsize,
|
|
edgefontcolor,
|
|
edgecolor,
|
|
bgcolor.
|
|
|
|
<dt>Version 1.18 2002/08/26<dd>
|
|
<ul>
|
|
<li> Can now specify class-local options.
|
|
<li> Support for the @tagvalue tag.
|
|
<li> Support for the @stereotype tag.
|
|
<li> Added nodefillcolor option.
|
|
</ul>
|
|
|
|
<dt>Version 1.15 2002/07/26<dd>First public release.
|
|
</dl>
|
|
|
|
<h3>More Examples</h3> <!-- {{{1 -->
|
|
<h3>Generalisation Relationships</h3> <!-- {{{2 -->
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
/*
|
|
* 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 {}
|
|
</pre>
|
|
</td><td>
|
|
<img src="general.gif">
|
|
</tr></table>
|
|
Download the <a href="general.java">declarative specification</a>, the generated <a href="general.dot">dot code</a>.
|
|
<h3>Advanced Relationships</h3> <!-- {{{2 -->
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
/*
|
|
* 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 - <friend> - SetTopController */
|
|
class ChannelIterator {}
|
|
|
|
interface URLStreamHandler {
|
|
void OpenConnection();
|
|
void parseURL();
|
|
void setURL();
|
|
void toExternalForm();
|
|
}
|
|
</pre>
|
|
</td><td>
|
|
<img src="advrel.gif">
|
|
</tr></table>
|
|
Download the <a href="advrel.java">declarative specification</a>, the generated <a href="advrel.dot">dot code</a>.
|
|
<h3>Schema</h3> <!-- {{{2 -->
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
/*
|
|
* 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;
|
|
}
|
|
</pre>
|
|
</td><td>
|
|
<img src="schema.gif">
|
|
</tr></table>
|
|
Download the <a href="schema.java">declarative specification</a>, the generated <a href="schema.dot">dot code</a>.
|
|
<h3>Element Visibility</h3> <!-- {{{2 -->
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
/**
|
|
* 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() {}
|
|
}
|
|
</pre>
|
|
</td><td>
|
|
<img src="vis.gif">
|
|
</tr></table>
|
|
Download the <a href="vis.java">declarative specification</a>, the generated <a href="vis.dot">dot code</a>.
|
|
<h3>Association Types</h3> <!-- {{{2 -->
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
/**
|
|
* 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{}
|
|
</pre>
|
|
</td><td>
|
|
<img src="assoc.gif">
|
|
</tr></table>
|
|
Download the <a href="assoc.java">declarative specification</a>, the generated <a href="assoc.dot">dot code</a>.
|
|
<h3>Real Example (Catalina Classes)</h3> <!-- {{{2 -->
|
|
<pre>
|
|
/*
|
|
* 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 {}
|
|
</pre>
|
|
<img src="catalina.gif"><br>
|
|
Download the <a href="catalina.java">declarative specification</a>, the generated <a href="catalina.dot">dot code</a>.
|
|
<h3>Class Stereotypes and Tagged Values</h3> <!-- {{{2 -->
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
/*
|
|
* 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() {};
|
|
}
|
|
</pre>
|
|
</td><td>
|
|
<img src="classadd.gif">
|
|
</tr></table>
|
|
Download the <a href="classadd.java">declarative specification</a>, the generated <a href="classadd.dot">dot code</a>.
|
|
<h3>Colors, Global and Local Options</h3> <!-- {{{2 -->
|
|
<table>
|
|
<tr><td>
|
|
<pre>
|
|
/**
|
|
* @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{}
|
|
</pre>
|
|
</td><td>
|
|
<img src="color.gif">
|
|
</tr></table>
|
|
Download the <a href="color.java">declarative specification</a>, the generated <a href="color.dot">dot code</a>.
|
|
<!-- End matter {{{1 -->
|
|
<p>
|
|
<a href="../../">Diomidis Spinellis home page</a>
|
|
<HR> <P>
|
|
<font size=-2>
|
|
$Id$<br>
|
|
(C) Copyright 2002 Diomidis D. Spinellis.
|
|
May be freely uploaded by WWW viewers and similar programs.
|
|
All other rights reserved.
|
|
</font>
|
|
</BODY>
|
|
</HTML>
|