UMLGraph/doc/ceg-mvi.xml

<?xml version="1.0" ?>
<!-- $Id$ -->
<notes>
Documenting a big project often requires multiple diagrams:
each to show a specific and limited portion of the system.
Each diagram is usually composed of few classes, possibily using a different detail level.<p/>
The <code>@view</code> tag, marks a special class used to describe a single class diagram.
Similarly to UMLOptions, the view can define its own general options,
but allows to define <em>overrides</em> that allow to adopt different options 
for different classes based on regular expressions matching.
The general syntax for defining a view is:
<fmtcode ext="java">
/**
 * @view
 * @opt [!]viewOption1
 * @opt [!]viewOption2
 * ...
 * @match regularExpression1
 * @opt [!]option1.1 [argument]
 * @opt [!]option1.2 [argument]
 * ...
 * @match regularExpression2
 * @opt [!]option2.1 [argument]
 * @opt [!]option2.2 [argument]
 * ... 
 */
</fmtcode>

The view options are applied to every class in the view (so they are the
global options for this class diagram).<br/>
The regular expression will be used to match a single class, a group of 
classes, or a package, and the options that follow will be applied to
those classes. <br/>
Multiple matches will be evaluted in the order of specification.<br/>
Refer to the <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">Pattern</a> 
class documentation for details on a proper regular expression specification.

<p/>Each view will generate a .dot file whose name is the name of the view,
unless the "output" option is specified to override it.

<h2>View inheritance</h2>

View classes can inherit from other view classes, allowing views to
share a set of common matches. The standard java inheritance mechanism
is used to specify inheritance.<br/>
Abstract view classes won't be used to generate diagrams, the common
idiom is to declare a base abstract view to share common options and
overrides, and have concrete view classes that extend for diagram generation.

<h2>Example: views at different detail of specification</h2>

The previous multiple view example can be generated by using internal
view support by means of the following sources (note the use of UmlOptions
to set the common appearance options, and the views to generate multiple
diagrams at different detail level).

<fmtcode ext="java">
// Author:  Vadim Nasardinov
// Author:  Andrea Aime
// Version: $Id$

import java.util.List;
import java.util.Map;

/**
 * @assoc "1..1" - "0..n" Adapter
 * @assoc "" - "0..n" ObjectType
 * @assoc "" - "0..n" ObjectMap
 * @assoc "" - "0..n" Table
 * @assoc "" - "0..n" DataOperation
 **/
class Root {
    private Map m_adapters;
    private List m_types;
    private List m_maps;
    private List m_tables;
    private List m_ops;

    public Adapter getAdapter(Class klass) {}
}

class Adapter {
    public Root getRoot();
}

abstract class Element {
    Root getRoot() {}
}

class ObjectType extends Element {}

/**
 * @has "1..1" - "1..1" ObjectType
 **/
class ObjectMap extends Element {
    private ObjectType m_type;
}

class Table extends Element {}

class DataOperation extends Element {}

/**
 * @hidden
 * @opt nodefontname luxisr 
 * @opt nodefontabstractname luxisri
 * @opt edgefontname luxisr
 * @opt nodefontsize 8 
 * @opt edgefontsize 8
 * @opt nodefillcolor LemonChiffon
 */
class UMLOptions {}

/**
 * @view
 * @opt attributes
 * @opt operations
 */
class DetailedView {}

/**
 * @view
 */
class Overview {}
</fmtcode>

and by invoking the following commands (assuming UmlGraph.jar is in the
current directory):

<fmtcode ext="bat">
javadoc -doclet gr.spinellis.umlgraph.doclet.UmlGraph -private -docletpath UmlGraph.jar -views RootViews.java
dot -Tpng -o root-small.png Overview.dot
dot -Tpng -o root.png DetailedView.dot
</fmtcode>

<h2>Example: per package views</h2>

Views are especially interesting in big projects, since they allow to
generate package specific diagrams and overview diagrams in a quick and
consistent way. <br/>

As an example we include a few class diagrams that have been generated
from the <a href="http://jakarta.apache.org/commons/dbcp">DBCP connection pool</a>, 
without altering the sources and using association and dependency inference 
instead.<br/>

The base view defines commons options, in particular the use of inference,
common class coloring and class visibility (in particular, we hide the
java runtime classes, with the exclusion of a few java.sql classes).
To avoid visual clutter, we have first shown the java.sql package contents, and
then hid selected classes.
The <code>Overview</code> view provides a full view of the DBCP package,
generating quite a big diagram (click on the diagram to show a full size version).<br/>

<fmtcode ext="java">
package org.apache.commons;

/**
 * @view
 * @opt inferassoc
 * @opt inferdep
 * @opt useimports
 * 
 * @match .*
 * @opt nodefillcolor LightGray
 * 
 * @match org.apache.commons.*
 * @opt nodefillcolor PaleGreen
 * 
 * @match org.apache.commons.dbcp.*
 * @opt nodefillcolor LemonChiffon
 * 
 * @match java.*|org.xml.*
 * @opt hide
 * 
 * @match java.sql.*
 * @opt !hide
 * 
 * @match java.sql\.(Ref|Time|Timestamp|Array|Date|Time|Clob|Blob|SQLException|.*MetaData.*|SQLWarning)
 * @opt hide
 */
public abstract class BaseView {
}

/**
 * @view
 */
public class Overview extends BaseView {
}
</fmtcode>

<a href="dcbp-overview-full.png"><img src="dbcp-overview-small.png" alt="Overview"/></a>

<p/>The <code>CommonsDbcp</code> view concentrates on the content of org.apache.commons.dbcp
package, hiding other packages and subpackages available in the sources
(click on the diagram to show a full size version).<br/>

<fmtcode ext="java">
package org.apache.commons;

/**
 * @view
 * 
 * @match org.apache.commons.*
 * @opt hide
 * 
 * @match org.apache.commons.dbcp..*
 * @opt !hide
 * 
 * @match org.apache.commons.dbcp..*\..*
 * @opt hide
 */
public class CommonsDbcp extends BaseView {}
</fmtcode>

<a href="dcbp-full.png"><img src="dbcp-small.png" alt="Overview"/></a>

<p/>Finally, the <code>Statement</code> view shows only the Statement related
classes and their dependencies.

<fmtcode ext="java">
package org.apache.commons;

/**
 * @view
 * 
 * @match org.apache.commons.*
 * @opt hide
 * 
 * @match org.apache.commons.dbcp\..*Statement.*
 * @opt !hide
 * 
 * @match org.apache.commons.dbcp..*\..*
 * @opt hide
 */
public class Statement extends BaseView {
}
</fmtcode>

<img src="dbcp-statement.png" alt="Statement"/>

</notes>