mapss.dif.graph
Class DotGenerator

java.lang.Object
  mapss.dif.graph.DotGenerator

Direct Known Subclasses:

DIFToDot

public class DotGenerator
extends java.lang.Object

Dot file or string generator for GraphViz graph visualization package. Any graph that will be used as an input to this class should have a valid clone() method. This is because the graph object passed to the DotGenerator is cloned and cached.

Output files (or strings) obtained from this class can be fed to Dot or Neato tools of the GraphViz package to generate graphical representations of mocgraph.Graph objects. GraphViz package is developed by AT&T labs and can be found at www.graphviz.org.

Although Dot and Neato are intended for directed and undirected graphs respectively they can handle both kind of graph inputs. Input files are written in "Dot File Format" and generated files will automatically have a ".dot" extension. For more information about the usage of these tools, refer to GraphViz documentation.

DotGenerator class provides two ways for creating dot files (or strings). First is using the static toFile methods which don't require constructing a DotGenerator object. These methods use the default settings for node and edge attributes. By default, node labels are copied from the graph using nodeLabel method and node shapes are ellipses. Second way is by constructing an object and using its methods. This is required if one needs to change the default attributes or add new attributes to the visual graph. A clone of the original graph is used in the DotGenerator object for caching.

To run dot or neato to create a Postscript file following commands can be used in command prompt:

dot | neato -Tps inputFile -o outputFile

For further commands see GraphViz documentation.

Version:

$Id: DotGenerator.java 409 2007-05-13 19:47:16Z plishker $

Author:

Fuat Keceli

See Also:

Graph

Field Summary

protected java.util.HashMap	_clusterAttributes HashMap: Collection cluster -> StringBuffer
protected java.util.Vector	_clusters Each element is a Collection of Nodes.
protected java.util.HashMap	_elementAttributes HashMap: Element -> (AttributeName -> AttributeValue)
protected java.lang.StringBuffer	_extraLines Extra lines/attributes to be added to a graph description before topology definitions.
protected mocgraph.Graph	_graph Clone of the original graph given in the constructor.
protected boolean	_isDirected Should be set to true if the graph is directed.
protected java.lang.String	_name Name of this graph.

Constructor Summary

protected	DotGenerator()
	DotGenerator(mocgraph.Graph graph) Constructs DotGenerator object associated with a graph.

Method Summary

void	addLine(java.lang.String line) Inserts a line to before the dot description in a graph.
boolean	isClusterNode(mocgraph.Node node) Returns true if this node is defined within a cluster previously.
boolean	setAsDirected(boolean directed) Sets the DotGenerator object to represent the graph as directed.
boolean	setAttribute(java.util.Collection clusterNodes, java.lang.String line) Sets an attribute in the cluster.
java.lang.String	setAttribute(mocgraph.Element graphElement, java.lang.String attribute, java.lang.String value) Sets an attribute for a node in the graph.
boolean	setCluster(java.util.Collection clusterNodes) Sets a group of nodes as a cluster.
java.lang.String	setGraphName(java.lang.String name) Sets the name for this graph and adds a line to the graph definition to print this name to GraphViz.
static void	toFile(mocgraph.Graph graph, java.lang.String fileName, boolean isDirected) Creates fileName.dot from the given graph.
void	toFile(java.lang.String fileName) Creates fileName.dot from the DotGenerator object.
java.lang.String	toString() Creates "dot" code string of the DotGenerator object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_graph

protected mocgraph.Graph _graph

Clone of the original graph given in the constructor.

See Also:

Graph.clone()

_name

protected java.lang.String _name

Name of this graph.

_elementAttributes

protected java.util.HashMap _elementAttributes

HashMap: Element -> (AttributeName -> AttributeValue)

_clusterAttributes

protected java.util.HashMap _clusterAttributes

HashMap: Collection cluster -> StringBuffer

_clusters

protected java.util.Vector _clusters

Each element is a Collection of Nodes. Purpose of this field is to keep the definition order of clusters for deterministic output.

_extraLines

protected java.lang.StringBuffer _extraLines

Extra lines/attributes to be added to a graph description before topology definitions.

_isDirected

protected boolean _isDirected

Should be set to true if the graph is directed.

Constructor Detail

DotGenerator

protected DotGenerator()

DotGenerator

public DotGenerator(mocgraph.Graph graph)

Constructs DotGenerator object associated with a graph. It uses a clone of the provided graph to avoid consistency issues.

This is only required if you need to change the default attributes of the visual graph. Otherwise it is easier to use the static methods.

Parameters:

graph - A Graph object.

Method Detail

addLine

public void addLine(java.lang.String line)

Inserts a line to before the dot description in a graph. This can be used to add attributes to the graph such as label = "graph_name"; . Semicolons should be included at the end of the line.

Parameters:

line - Line to be added to the dot description of the graph. A line feed will automatically be added to the end of the line.

isClusterNode

public boolean isClusterNode(mocgraph.Node node)

Returns true if this node is defined within a cluster previously.

Parameters:

node - A graph node.

setAsDirected

public boolean setAsDirected(boolean directed)

Sets the DotGenerator object to represent the graph as directed. Default value for this option is false (undirected).

Returns:

Previous value of the option.

setAttribute

public boolean setAttribute(java.util.Collection clusterNodes,
                            java.lang.String line)

Sets an attribute in the cluster. This is similar to the way that addLine(java.lang.String) works.

Parameters:

clusterNodes - Cluster for which the attribute is going to be set.

line - Attribute string

Returns:

False if the list of nodes could not be found as a cluster.

setAttribute

public java.lang.String setAttribute(mocgraph.Element graphElement,
                                     java.lang.String attribute,
                                     java.lang.String value)

Sets an attribute for a node in the graph. For possible attributes and values consult to GraphViz documentation. Note that if an attribute value should include quotes they should be manually placed in the string. If a value is not needed for this attribute use null.

ex: setAttribute(graphNode,"label","\"my_node\"")

This method is case sensitive for attributes and values.

Parameters:

graphElement - A node or edge of the graph to set an attribute for.

attribute - Attribute that is going to be set.

value - Value for the attribute. Use null if there is no need for a value.

Returns:

The previous value of this attribute if it exists, null otherwise.

setCluster

public boolean setCluster(java.util.Collection clusterNodes)

Sets a group of nodes as a cluster. These nodes will be defined as a sub-group in the dot definition. This method will do nothing and return false in two cases: At least one of the nodes is not contained in the graph or at least one of the nodes is defined to be in another cluster. Note that once run this command can't be undone.

Parameters:

clusterNodes - A collection of nodes.

Returns:

False if there is an error.

setGraphName

public java.lang.String setGraphName(java.lang.String name)

Sets the name for this graph and adds a line to the graph definition to print this name to GraphViz. This method is useful when multiple graph definitions are put in a single file.

Parameters:

name - Name of the graph. It shouldn't include white space or punctuation.

Returns:

Previous value of the name.

toFile

public void toFile(java.lang.String fileName)
            throws java.io.IOException

Creates fileName.dot from the DotGenerator object.

Parameters:

fileName - Name of the dot file to be created. A ".dot" extension will be appended to this name.

Throws:

java.io.IOException - If the file could not be created.

toFile

public static void toFile(mocgraph.Graph graph,
                          java.lang.String fileName,
                          boolean isDirected)
                   throws java.io.IOException

Creates fileName.dot from the given graph.

Parameters:

graph - A Graph object.

fileName - Name of the dot file to be created. A ".dot" extension will be appended to this name.

isDirected - True if the graph is directed, false otherwise.

Throws:

java.io.IOException - If the file could not be created.

toString

public java.lang.String toString()

Creates "dot" code string of the DotGenerator object.

Overrides:

toString in class java.lang.Object

Returns:

The "dot" code.