<?xml version="1.0" ?>
<!-- $Id$ -->
<notes>
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 was not originally designed for this purpose;
the resulting graphs may be large and unwieldy.
<p />
There are various ways to invoke UMLGraph,
each providing a different balance between convenience and flexibility.
<h2>Option 1: Using the Supplied Script</h2>
This is the simplest option.
If <code>umlgraph</code> (or <code>umlgraph.bat</code>) 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:
<fmtcode ext="sh">
umlgraph Test png
</fmtcode>
Any additional UMLGraph or <em>javadoc</em> 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).
<h2>Option 2: Running Java</h2>
This option provides the maximum flexibility.
In order to run, <em>javadoc</em> needs to access <code>tools.jar</code>.
You can accomplish this in two ways.
<ol>
<li>
Specify the location of <code>tools.jar</code> 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
<fmtcode ext="bat">
java -classpath "lib/UmlGraph.jar;c:\program files\java\jdk1.6.0_02\lib\Tools.jar"
    org.umlgraph.doclet.UmlGraph -package Test.java
</fmtcode>
and under Unix
<fmtcode ext="sh">
java -classpath '/usr/share/lib/UmlGraph.jar:/opt/Java-1.6/lib/tools.jar' \
org.umlgraph.doclet.UmlGraph -package Test.java
</fmtcode>
</li>
<li> Place the <code>UmlGraph.jar</code>
file in a directory that also contains the Java SDK <code>tools.jar</code> file.
You can accomplish this either by copying <code>UmlGraph.jar</code> to the SDK
<code>lib</code> directory where <code>tools.jar</code> resides,
or by copying the JDK <code>tools.jar</code> file into the directory
where you installed UMLGraph.
You then run
<fmtcode ext="sh">
java -jar /path/to/UmlGraph.jar yourfile1.java ...
</fmtcode>
</li>
</ol>
You can use any of the <em>javadoc</em> general options;
<code>-private</code> is usually needed to avoid having to explicitly
specify public elements.
Example:
<fmtcode ext="sh">
java -jar /usr/jvm/java-1.5.0/lib/UmlGraph.jar -private Simple.java
</fmtcode>
<p />
Specifying some packages before the list of source files will designate
those packages as <em>local</em>.
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.
<p />

<h2>Option 3: Running Javadoc</h2>
Alternatively, you can also run <em>UMLGraph</em> from within <em>javadoc</em>.
This can be useful if your IDE provides additional support for running <em>javadoc</em>.
In this case you run
<em>javadoc</em> with arguments <code>-doclet org.umlgraph.doclet.UmlGraph</code>
<code>-docletpath /path/to/UmlGraph.jar</code>
and append at the end the file(s) that contain your diagram
specification.
Example:
<fmtcode ext="sh">
javadoc -docletpath UmlGraph.jar -doclet org.umlgraph.doclet.UmlGraph -private Simple.java
</fmtcode>

<h2>Running Dot</h2>
The last two options, will generate the UML diagram in
<em>Graphviz</em> <em>dot</em> format.
This is a text file that can be processed by the <em>Graphviz</em> <em>dot</em>
program to layout and draw the graph.
<em>javadoc</em> will create by default a file named <code>graph.dot</code>
in the current directory.
A command line like the following will convert the <code>graph.dot</code>
file into Postscript:
<fmtcode ext="sh">
dot -Tps -ograph.ps graph.dot
</fmtcode>
or PNG
<fmtcode ext="sh">
dot -Tpng -ograph.png graph.dot
</fmtcode>
Refer to the <em>dot</em> documentation for information on creating other file formats
or adjusting the UMLGraph output.
<p />
You also can pipe the result of <em>UMLGraph</em> directly into <em>dot</em>:
<fmtcode ext="sh">
java -jar /.../UmlGraph.jar -private -output - Simple.java | dot -Tgif -ograph.gif
</fmtcode>
<p />
Note that when you use <em>dot</em> for generating SVG diagrams your
should specify the <code>-outputencoding UTF-8</code> option to UMLGraph.
This option will correctly render the stereotype guillemot characters
in the <em>dot</em> output and the corresponding SVG file.
</notes>
