-
+
+
+
- Grady Booch, James + Rumbaugh, and Ivar Jacobson. +The + Unified Modeling Language User Guide. +Addison-Wesley, Reading, MA, 1999. + + +
- Martin Fowler and + Kendall Scott. +UML + Distilled: Applying the Standard Object Modeling Language. +Addison-Wesley, Boston, MA, second edition, 2000. + + +
- Emden R. Gasner, + Eleftherios Koutsofios, Stephen C. North, and Kiem-Phong Vo. +A technique for drawing directed graphs. +IEEE Transactions on Software Engineering, 19(3):124–230, May + 1993. + + +
- Brian W. Kernighan. +PIC—a graphics language for typesetting: Revised user manual. +Computer Science Technical Report 116, Bell Laboratories, Murray Hill, NJ, + December 1984. +Available online at http://cm.bell-labs.com/cm/cs/cstr. + + +
- James Rumbaugh, Ivar + Jacobson, and Grady Booch. +The + Unified Modeling Language Reference Manual. +Addison-Wesley, Reading, MA, 1999. + + +
- Diomidis Spinellis. +Code Reading: The Open + Source Perspective. +Addison-Wesley, Boston, MA, 2003. + + +
- Diomidis Spinellis. +On the declarative specification of models. +IEEE Software, 20(2):94–96, March/April 2003. + +
|
+ |
+
+ |
-
+
- classes (specified as Java classes) + +
- attributes (specified as Java class fields) + +
- operations (specified as Java class methods) + +
- stereotypes (using the
@stereotypename tag) +
+ - tagged values (using the
@tagvaluename value tag) +
+ - implementation relationships (specified using the Java
implementsdeclaration) +
+ - generalization relationships (specified using the Java
extendsdeclaration or (for multiple inheritance) the javadoc@extendstag) +
+ - association relationships (specified using the javadoc
@assoctag) +
+ - navigatable (directed) association relationships (specified using the javadoc
@navassoctag) +
+ - aggregation relationships (specified using the javadoc
@hastag) +
+ - composition relationships (specified using the javadoc
@composedtag) +
+ - dependency relationships (specified using the javadoc
@dependtag) +
+
@extends take four arguments:
+-
+
- The source adornments (role, multiplicity, and visibility) + +
- The relationship name + +
- The target adornments (role, multiplicity, and visibility) + +
- The target class + +
+
+class Tyre {}
+class Engine {}
+class Body {}
+
+/**
+ * @composed 1 - 4 Tyre
+ * @composed 1 - 1 Engine
+ * @composed 1 - 1 Body
+ */
+class Car {}
+
+ |
+
+ |
@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 gr.spinellis.umlgraph.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.
+
+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.
+
+Example:
+graph.dot
+in the current directory; option to
+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:
+-outputencoding UTF-8 option to UMLGraph.
+This option will correctly render the stereotype guillemot characters
+in the dot output and the corresponding SVG file.
+-
+
- -output
- Specify the output file name (default
graph.dot). +
+ - -outputencoding
- Specify the output encoding character set (default
ISO-8859-1). +When using dot to generate SVG diagrams you should specify +UTF-8as the output encoding, to have guillemots correctly +appearing in the resulting SVG. +
+ - -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) + +
- -constructors
- Show a class's constructors + +
- -visibility
- Adorn class elements according to their +visibility (private, public, protected, package) + +
- -types
- Add type information to attributes and operations + +
- -enumerations
- Show enumarations as separate stereotyped primitive +types. + +
- -enumconstants
- When showing enumerations, also show the values they can take. + +
- -all
- Same as
+
-attributes+-operations+-visibility+-types+-enumerations+-enumconstants+
+ - -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. + +
- -hide
- Specify entities to hide from the graph.
+Matching is done against the end of each entity's name.
+For instance, "
-hide Widget" would hide "com.foo.widgets.Widget" and +"com.foo.widgets.BigWidget". +
+ - -apidocroot
- Specify the URL that should be used as the "root" for local classes.
+This URL will be used as a prefix, to which the page name for the local class or
+package will be appended (following the JavaDoc convention).
+For example, if the value
http://www.acme.org/apidocsis +provided, the classorg.acme.util.MyClasswill be mapped to the URL +http://www.acme.org/apidocs/org/acme/util/MyClass.html. +This URL will then be added to .dot diagram and can be surfaced in the +final class diagram by setting the output to SVG, or by creating an HTML page +that associates the diagram static image (a .gif or .png) with a client-side +image map. +
+ - -apidocmap
- Specify the file name of the URL mapping table. +The is a standard Java property file, where the property name is a regular +expression (as defined in the java.util.regex package) and the property value is +an URL "root" as described above. +This table is used to resolved external class names (class names that do not +belong to the current package being processed by UMLGraph). If no file is provided, +external classes will just be mapped to the on-line Java API documentation. + +
- -noguillemot
- Specify that guillemot characters should not +be used to denote special terms like "interface" and stereotype names. +This is used on some platforms to circumvent problems associated +with displaying non-ASCII characters. + +
@opt tags in front
+of a class named UMLOptions, as in the following example:
+@opt attributes on individual classes.
+In this case the @opt specification temporarily overrides
+the particular global setting for the class being processed.
+
+|
+ |
+
+ |
|
+ |
+
+ |
+
|
+ |
+
+ |
|
+ |
+
+ |
|
+ |
+
+ |
Class Overview
+
+
+Detailed Class View
+
+
+Java Description
+Makefile
+|
+ |
+
+ |
|
+ |
+
+ |
Diagram
+
+Diagram Source Code
+Diagram
+
+Diagram Source Code
+Contents
+-
+
+
- Why are the SVG diagrams dot generates malformed? +
- How can I improve the quality of the bitmap images I generate? +
- How can I improve the layout of my class diagrams? +
- A class appears multiple times in a class diagram. Why? +
- Shouldn't static fields appear underlined? +
- Where can I find a pic2plot executable for Windows? +
- Under Windows the output of pic2plot appears empty. Why? +
- I have a problem with Maven's Dotuml plugin. Can you help me? +
- How can I make the UMLGraph doclet generate sequence diagrams? +
- Why the vanity package name? Why not name the package org.umlgraph? +
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: +-sPAPERSIZE=a4 or
+-dDEVICEHEIGHTPOINTS=1000 to avoid getting
+his resutls 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. +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
+First Approach: Class Name Qualified with the Package
+Second Approach: No Package Specification
+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: +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. + +Diagram
+
+Diagram Source Code
+-
+
- First of all, the model composition mechanism matches well both a programmer's high-level skills, the textual abstract formalization of concrete concepts, and the associated low-level skills, the manipulation of text using an editor and other text-based tools. +
- The declarative notation, by being closer to the program's representation (the notation I experimented with is based on the Java syntax and semantics), forces the designer to distinguish between the model and the respective implementation, between the essential system characteristics and the trivial adornments. + It is more difficult for designers to get away, as they often do now, with drawing for a model a nice picture of the implementation they have in mind. +
- The declarative representation is also highly malleable, the existing visual structure does not hinder drastic changes, nor is effort wasted on the tidy arrangement of graph nodes a psychological barrier against massive design refactoring. +
- Declarative models are also highly automatable: they can be easily generated from even higher-level descriptions by trivial scripts and tools operating on design process inputs such as database schemas, existing code, or structured requirements documents. +
- Text macro processors can be used for configuration management, while revision control and team integration activities can utilize the same proven tools and processes that are currently used for managing source code. + Thus with a tool like CVS or RCS one can keep track of design revisions, create and merge branches, and monitor model changes, while a system like CVS can allow work to be split into teams. +
- Finally, the declarative approach can readily utilize existing text processing tools for tasks that a drawing editor system may not provide. +
-
+
- identify all classes containing a given field (as a prelude to an aspect-oriented cross-cut); +
- count the total number of private fields in a given design; +
- order methods appearing in multiple classes by their degree of commonality; +
- identify differences between two designs. +
+
+
+step(); call after we defined the objects,
+to provide them with a bit of breathing space.
+We also added a similar step call at the end of the diagram.
+Finally, we made both objects active, after their definition.
+Calling active on a given object will change the drawing of its
+lifeline, from the dashed format indicating an inactive object,
+to a thick swimming-lane, active object, format.
+
+The resultant diagram is+
+
+|
+ |
+
+ |
-
+
- object(name,label); +
- Defines an object with the given name, labeled on the diagram + as specified. +
- placeholder_object(name) +
- Defines a place where the named object will later be
+ created.
+ Can also be written as
pobject. +
+ - actor(name,label); +
- Defines an actor with the given name, labeled on the diagram + as specified. + Actors are typically used instead of objects to indicate operations + initiated by human actions. +
- complete(name); +
- Completes the lifeline of a given object (or actor) + by drawing its lifeline to the bottom of the diagram. +
- message(from_object,to_object,label) +
- Draws a message between two objects, with the given label. + Self messages (where an objects sends a message to itself) + are supported. + +
- return_message(from_object,to_object,label) +
- Draws a return message between two objects, with the given label.
+ Can also be written as
rmessage. +
+ - create_message(from_object,to_object,object_label); +
- Has from_object create the to_object, labeled
+ with object_label.
+ The message is labeled with the
«create»stereotype. + Can also be written ascmessage. +
+ - destroy_message(from_object,to_object); +
- Sends a message
+ labeled with the
«destroy»stereotype + from the from_object to the to_object. + The object to_object is marked as destroyed, with an X at the + end of its lifeline. + The object's lifeline need not be otherwise completed. + Can also be written asdmessage. +
+ - active(object); +
- Changes the object's status to active, and + changes its lifeline drawing style correspondingly. + An active call in an already active object will result + in a swimlane showing a nested object activation. +
- inactive(object); +
- Changes the object's status to inactive, and + changes its lifeline drawing style correspondingly. + An inactive call on a nested object invocation will + result in showing a simple active swimlane. +
- delete(object); +
- The object deletes itself, drawing an X at the end + of its lifeline. + The object's lifeline need not be otherwise completed. + +
- lifeline_constraint(object,label); +
- Displays a constraint label (typically given inside curly braces)
+ for the given object.
+ The constraint will appear on the right of the object's lifeline
+ at the time it appears.
+ Can also be used to place an message label on the left of a
+ message arrow, rather than its center.
+ Can also be written as
lconstraint. +
+ - lconstraint_below(object,label); +
- same as
lconstraint, + but it will be shown below the current line instead of above. +
+ - object_constraint(label) +
- Displays an object constraint (typically given inside curly braces)
+ for the last object defined.
+ Can also be written as
oconstraint. +
+ - step(); +
- Steps the time by a single increment, extending all + lifelines. +
- async(); +
- All subsequent messages are asynchronous and will + be drawn correspondingly. +
- sync(); +
- All subsequent messages are synchronous and will + be drawn correspondingly. +
- begin_frame(left_object,name,label_text); +
- Begins a frame with the upper left corner at
+
left_objectcolumn and the current line. + The specifiedlabel_textis shown in the upper left corner. +
+ - end_frame(right_object,name); +
- Ends a frame with the lower right corner at
+
right_objectcolumn and the current line. + The name must correspond to abegin_frame's name. +
+ - comment(object,[name],[line_movement],[box_size] text); +
- Displays a comment about the object.
+ The name can be used with
+
connect_to_comment(object2,name);to get additional + connecting lines to the comment. +line_movementchanges the position of the comment and +box_sizeits size. Note that there's no comma between +box_sizeandtext. +textis the (multiline) comment-text that will be displayed. +name,line_movementandbox_sizeare optional + (but the commas must still appear). +
+ - connect_to_comment(object2,name); +
- See
comment. +
+
-
+
- Object definition +
- Message exchange +
- Object lifeline completion +
.PS/.PE and
+copy "sequence.pic";
+elements.)
++
+
+.PS marks the beginning of pic commands.
+The sequence
+copy "sequence.pic";
+loads the macros defining the sequence diagram operations.
+The file sequence.pic, part of the UMLGraph distribution,
+must exist in the directory where pic2plot will be executed.
+
+Sequence diagram files must end with the sequence:
+O
+that will be identified in the diagram as
+o:Toolkit
+# character.
+| Variable Name | Default Value | Operation |
|---|---|---|
| boxht | 0.3 | Object box height |
| boxwid | 0.75 | Object box width |
| awid | 0.1 | Active lifeline width |
| spacing | 0.25 | Spacing between messages |
| movewid | 0.75 | Spacing between objects |
| dashwid | 0.05 | Interval for dashed lines |
| maxpswid | 11 | Maximum width of picture |
| maxpsht | 11 | Maximum height of picture |
Diagram
+
+Diagram Source Code
+Diagram
+
+Diagram Source Code
+Diagram
+
+Diagram Source Code
+Diagram
+
+Diagram Source Code
+-
+
+
- Version 4.2 Under development
-
+
-
+
- Correct the handling of qualified class names following +the extends keyword (Arnaud Rogues). +
- Version 4.1 2005/11/15
-
+
-
+
- Major source code reorganization to move closer to the Java coding
+conventions.
+The user-visible change is that the doclet is now invoked as
+
+javadoc -docletpath UmlGraph.jar -doclet gr.spinellis.umlgraph.doclet.UmlGraph + +
+ - Show package visibility for class members (Olek Poplavskyy). +
- Prevent crash when processing erroneous relation specifications (Andrea Aime). +
- Most loops were refarctored to use the typesafe Java 1.5 foreach construct. +
- Fix Eclipse warning (Andrea Aime). +
- Better control of class hiding. +Now classes are hidden even when involved in a relationship with a visible class +(Andrea Aime). +
- Source code modifications to allow Java-based testing (Andrea Aime). +
+
+ - Major source code reorganization to move closer to the Java coding
+conventions.
+The user-visible change is that the doclet is now invoked as
+
- Version 3.3 2005/10/19
-
+
-
+
- The sequence diagrams now include support for drawing +comments and frames. (Contributed by Sebastian Setzer) +
- The -noguillemot option will output two angle bracket pairs +instead of round brackets around stereotypes. +
+
+ - Version 3.2 2005/07/19
-
+
-
+
- Display the template arguments of generic classes inside angle brackets. +Note that according to the UML specification these arguments should +be displayed in a dashed box on the top right of the class. +However, such a display is currently not possible in GraphViz. +
- Display the type parameters of fields and method arguments. +
+
+ - Version 3.1 2005/03/26
-
+
-
+
- Note that from this version UMLGraph requires Java 1.5. +
- First step of the Java 1.5 transition; more will follow. +
- The container code in the source was changed to use the Java 1.5 generics. +
- Will display enumerations as a stereotyped primitive type.
+Two new options
-enumerationsand-enumconstants+control the corresponding operation.
+
+
+ - Version 2.10 2004/11/19
-
+
-
+
- This is the last version compatible with Java 1.4. +
- Corrected the interaction between the
+
-attributesand +-operationsoptions and classes with no +fields or methods. +Many thanks to Jonathan Wright for this contribution.
+ - New documentation look, designed by George Zouganelis +
+
+ - Version 2.9 2004/10/07
-
+
-
+
- Class diagrams can now include constructors, through the new
+
-constructorsoption.
+
+
+ - Class diagrams can now include constructors, through the new
+
- Version 2.8 2004/08/09
-
+
-
+
- Fixes to support the Maven plugin. +
- From this version onward, use the appropriate options to create +documentation links; no hyperlinks are created by default. +
+
+ - Version 2.7 2004/08/06
-
+
-
+
- The -noguillemot option will output round brackets around stereotypes, +instead of angle brackets. +The angle brackets appear to be breaking some programs. + +
+
+ - Version 2.6 2004/08/03
-
+
-
+
- Note that from this version UMLGraph requires Java 1.4. +
- Documentation example: multiple views from the same source. +Many thanks to Vadim Nasardinov for this contribution. +
- Documentation now includes a FAQ section. +
- Documented the fact that package names must be explicitly +specified in tags. Arne Bayer noticed the associated problem. +
- Correct handling of multiple space in tags. +Noted by Jeffrey M. Thompson which the help of +FindBugs. + +
- Completed customization of URL mapping. Now the mapping is fully +configurable and can be controlled by the use of two new options: +"-apiDocRoot" and -"apiDocMapFileName". +This change allows the creation of "clickable" +diagrams fully integrated with web-based documentation +(for example JavaDoc pages). +The upcoming UMLGraph Maven plugin will take full advantage of this feature. +Implementation contributed by Nascif Abousalh-Neto + +
- The -hide argument now accepts regular expressions. +
- Removed copy-pasted Java code that was introduced in version 1.24. +
- Some dot edges were missing a semicolon. This is now fixed. +
+
+ - Version 2.5 2004/06/15
- +The object swimlanes in a sequence diagram +can now show nested object invocations. +This very useful and non-trivial change was contributed by Jonathan R. Santos. + + +
- Version 2.4 2004/05/29
- +Will now generate local URL hyperlinks for packages specified in +the command line; and links to the Sun documentation for all +other packages. +Many thanks to Nascif Abousalh-Neto for contributing this change. + + +
- Version 2.3 2004/05/27
-
+
-
+
- +Remove hardcoded default node and edge fonts. +Thanks to Vadim Nasardinov for submitting the corresponding patch. + +
- +Generate javadoc hyperlink paths in a directory-tree structure; +do not show arcs on hidden classes. +Thanks to Alessandro Riva for submitting the corresponding patch. + +
+
+ - Version 2.2 2004/05/25
- +SVG class diagrams containing guillemot characters +for stereotypes +can now be made valid through a new -outputencoding option. +Use "-outputencoding UTF-8" when using dot to generate SVG diagrams. +Many thanks to Nascif Abousalh-Neto for bringing this problem to +my attention. + + +
- Version 2.1 2004/05/16
- +The guillemot characters used for the create and destroy stereotypes +are now portable between groff and pic2plot. +Many thanks to Scott Johnson (Duluth, MN) for recommending the change. + + + +
- Version 2.0 2004/05/09
-
+
-
+
- Support for drawing sequence diagrams. +
- New distribution format. +
- Browsable and printable documentation. +
- Removed the ant-based compilation and distribution +system; it was proving a hindrance in organizing the project in +a resonable manner. +Compiling the documentation and distribution is now handled by +a (non-distributed) Makefile; the compilation process is described +in the README file. + +
+
+ - Version 1.24 2003/07/30
-
+Changes by Art Hampton (thanks):
+
-
+
- Create the appropriate label for relationship tags when referring to + classes which were not parsed by javadoc. + +
- New "-hide <matchstring>" option, where <matchstring> +matches the end of the name of an entity. +Matched entities are removed from the graph. +A regular expression matching facility will be added when Java 1.4 +becomes more widespread. + +
+ - Version 1.23 2003/05/7
-
+Added
-outputcommand-line option, and an ant-based +build file. +Modified the dot output to avoid triggering a graphviz bug that made escape codes visible. + +
+ - 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
-
+
-
+
- Can now specify class-local options. + +
- Support for the @tagvalue tag. + +
- Support for the @stereotype tag. + +
- Added nodefillcolor option. + +
+ - Version 1.15 2002/07/26
- First public release. + +