This interface represents the aspects common to all Graph elements, including a Node, Edge and Subgraph.

GraphObjects have an identifiable nature. Every GraphObject has both an identifier unique to its context as well as a global identifier that is unique within a hierarchy of Graph objects.

In the section GraphObject IDs both kinds of identifiers are explained in detail.
Methods to access both of these identifiers are available.

It is possible to associate a name and a description with a GraphObject. These can be used for example to easily assign a type and a descriptive text to the GraphObject.

The standard attributes of a GraphObject may be extended with custom attributes. The custom attributes added to the GraphObject are grouped into the category custom and returned by a call to getAttributes. The methods provided by a GraphObject to handle custom attributes are listed below:

The interface Node extends GraphObject, allowing nodes to be identified and labeled. Adding and removing nodes to and from a Graph is done by invoking methods on a Graph instance. This is not a part of the Node responsibility. The following is a list of important methods provided by this interface:

Like Node, interface Edge extends the GraphObject interface. Our particular implementation consists of convenience methods allowing you to retrieve the information stored in the Edge instance. Adding and removing edges to and from a Graph is done by invoking methods on a Graph instance and is not a functionality provided by this interface. Some important methods are:

The Port interface defines the characteristics of a single connection point to a Node from which an Edge instance is attached. In other words, an Edge connects to a Node via one of the many Port instances owned and managed by a Node, and not to the Node directly.

A Port uses a so-called PortDenotation, a named meta-level object which defines and returns the rules for incoming and outgoing connections, including their cardinalities.

Ports have identifiers which can be returned to clients who request them.

The important methods of this interface are:

This interface defines the responsibilities for containers of objects of type GraphObject. By providing this interface, different component types are able to play this role.

Orphaned nodes and edges are of no use in a graph model. Although such objects may be allocated on their own, they are usually added to a particular Graph instance, which internally assigns them a unique identifier within the scope of the Graph itself. Moreover, when an Edge is added to a Graph, additional checks are performed. For example, it is not permitted to add an Edge that refers to a Node not already contained by the Graph.

These are the more important methods defined in the interface:

This interface defines an abstract Graph without any notion of a visualization. This class can be used on its own for applying graph algorithms and for deriving specialized graph classes. Both directed and undirected graphs are supported. A Graph consists of Node and Edge objects. These are the parts of the graph model that can be accessed through the Graph interface and whose abstraction is commonly defined in the base interface GraphObject. This component interface defines the functionality common to both nodes and edges, as illustrated in the following class diagram.

Constructing a Graph and its related objects is done by means of a GraphModelFactory, which will hide the particular implementation classes from client code.

Upon adding, the ID of any GraphObject is automatically assigned. Before adding, however, the ID should be set to -1. Each GraphObject may only be added to at most one Graph instance. Adding it to a Graph instance instance while still managed by another will produce an exception. Removing a GraphObject will reset its ID to -1.

These are the more important methods defined in the interface:

Next we will provide a small code sample to show how a graph model is built. Before we do so, however, we have to clarify yet another important architectural facet of the Tensegrity Graph Framework.

Instead of directly creating objects using constructors, we have provided factory classes specialized to provide this functional responsibility. In some implementations, application-specific code can be full of calls to create new objects, causing this code to become brittle over time: Introducing new implementation classes that are better-designed to handle specific requirements would cause the application code to be changed and recompiled. This is the usual place where bugs find their way into systems.

Factory classes have the limited responsibility of creating new objects and returning them to clients. Code which uses a factory does not have to worry about which implementation class is used. This information is part of the responsibility of the factory implementation and can be configured by the application engineer. In other words, implementation details can be changed without violating the client contract. Please have a look at [GoF99] if you are unfamiliar with this pattern.

Creating an instance of type Graph, as well as all related model objects, is done by using a class derived from GraphModelFactory. The same is true for view and visual objects: They are created by methods defined in the abstract base class GraphViewFactory.

Now that we have introduced to you the fundamental objects that are required for assembling a Graph, we provide the following example which illustrates how to create a simple directed graph with four nodes (N) and four edges (E), such that:

N = {a, b, c, d} and E = { (a, b), (a, c), (c, d), (d, a) }
      

Building this graph with the Tensegrity Graph Framework is easy:

// First we have to obtain a factory to build our graph model
GraphModelFactory factory = GraphModelFactory.newInstance();
        
// instantiate a graph object
Graph graph = factory.newGraph();
        
// adding nodes and edges to the graph instance
try
{   
    // create nodes.
    // empty list of ports -> nodes have no ports
    List ports = new ArrayList();
    Node a = factory.newNode ("a", ports);
    Node b = factory.newNode ("b", ports);
    Node c = factory.newNode ("c", ports);
    Node d = factory.newNode ("d", ports);
    
    // add nodes to graph
    graph.addNode (a);
    graph.addNode (b);
    graph.addNode (c);
    graph.addNode (d);
    
    // create edges
    Edge ab = factory.newEdge (a, b);
    Edge ac = factory.newEdge (a, c);
    Edge cd = factory.newEdge (c, d);
    Edge da = factory.newEdge (d, a);
    
    // add the edges to the graph
    graph.addEdge (ab);
    graph.addEdge (ac);
    graph.addEdge (cd);
    graph.addEdge (da);
    
    System.out.println(graph);
}
catch (GraphException e)
{
    // handle graph exception here
    System.err.println(e);
}

In order to reduce the coding effort, as well as to have a more handy way of assembling a Graph manually, it would be more convienient to build two arrays holding Node and Edge instances and then use the addNodes and addEdges methods to add these model elements to the Graph in one call.

            
// create and add nodes
// empty list of ports -> nodes have no ports
List ports= new ArrayList();
Node nodes[]= { 
        factory.newNode("a", ports), 
        factory.newNode("b", ports), 
        factory.newNode("c", ports), 
        factory.newNode("d", ports)};
        
graph.addNodes(nodes);
            
// create and add edges
Edge edges[]= { 
        factory.newEdge(nodes[0], nodes[1]),
        factory.newEdge(nodes[0], nodes[2]),
        factory.newEdge(nodes[1], nodes[3]),
        factory.newEdge(nodes[3], nodes[0])};
        
graph.addEdges(edges);

Both examples result in identical graphs. Please have a look at the following screenshot to get an impression what this Graph might look like.

Figure 1.1. Example Graph

In most programming cases, it is far more convenient to use the later form, as one can always reference individual nodes by their array index.