com.tensegrity.graph.model
Interface GraphObjectContainer

All Known Subinterfaces:

Graph, Subgraph

public interface GraphObjectContainer

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.

Constructing a GraphObjectContainer is done by means of a GraphModelFactory, which will hide the particular implementation classes from client code.

The interfaces Graph and Subgraph are the concrete interface types that you will request from this factory.

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.

GraphObjectContainer instances that are dereferenced will be garbage collected.

This interface has methods which you can use to control the propagation of model events to listeners.

Version:

$Id: GraphObjectContainer.java,v 1.21 2006/03/13 11:08:42 MichaelKegel Exp $

Author:

Stepan Rutz

See Also:

Node, Edge, Graph, Subgraph, Port, GraphObject

Method Summary

void	addEdge(Edge edge) Adds the given edge to the GraphObjectContainer.
void	addEdges(Edge[] edges) Convenience method to add several edges to the GraphObjectContainer in one go.
void	addNode(Node node) Adds the given node to the GraphObjectContainer.
void	addNodes(Node[] nodes) Convenience method to add several nodes to a GraphObjectContainer in one go.
int[]	buildAdjacencyMatrix() Builds the adjacency matrix for this GraphObjectContainer.
void	disableGraphEvents(int eventmask) Disables all of the events specified in the given eventmask.
void	disableGraphEventsInternal(int eventmaskInternal) Disables all of the events specified in the given eventmask.
void	enableGraphEvents(int eventmask) Enables all of the events specified in the given eventmask.
void	enableGraphEventsInternal(int eventmaskInternal) Enables all of the events specified in the given eventmask.
Edge	findMultiEdge(Edge edge) Finds a multi edge for the given edge (the given edge is not added to the GraphObjectContainer at this point in time).
GraphEvent	fireCascadeNodeDeleteInternal(Node node, Edge newEdge, GraphObjectContainer newEdgeGOC, Edge oldEdge1, GraphObjectContainer oldEdge1GOC, Edge oldEdge2, GraphObjectContainer oldEdge2GOC) Fires a cascade node delete event.
GraphEvent	fireEdgeSplitInternal(Node node, long oldEdgeID, Edge oldEdge, GraphObjectContainer oldEdgeGOC, Edge newEdge1, GraphObjectContainer newEdge1GOC, Edge newEdge2, GraphObjectContainer newEdge2GOC) Fires an edge split event.
void	fireNodePreRemove(Node node) Fires a fireNodePreRemove event.
void	fireNodeRemoved(Node node, long previd) Fires a fireNodeRemoved event.
void	firePreCascadeNodeDeleteInternal(Node node, Edge newEdge, GraphObjectContainer newEdgeGOC, Edge oldEdge1, GraphObjectContainer oldEdge1GOC, Edge oldEdge2, GraphObjectContainer oldEdge2GOC) Fires a pre-cascade node delete event.
void	firePreEdgeSplitInternal(Node node, long oldEdgeID, Edge oldEdge, GraphObjectContainer oldEdgeGOC, Edge newEdge1, GraphObjectContainer newEdge1GOC, Edge newEdge2, GraphObjectContainer newEdge2GOC) Fires a pre-edge split event.
Edge[]	getEdgeArray() Returns an array of all edges, which is suitable for random access.
Edge	getEdgeByID(long localId) Returns the Edge with the given id.
int	getEdgeCount() Retrieves the number of edges from the GraphObjectContainer.
java.util.Iterator	getEdges() Retrieves an Iterator for all edges in the GraphObjectContainer.
int	getEventmask() Returns the current event mask of the GraphObjectContainer.
int	getEventmaskInternal() Returns the current internal event mask of the GraphObjectContainer.
Node[]	getNodeArray() Returns an array of all nodes, which is suitable for random access.
Node	getNodeByID(long localId) Returns the Node with the given id.
int	getNodeCount() Retrieves the number of nodes from the GraphObjectContainer.
java.util.Iterator	getNodes() Retrieves an Iterator for all nodes.
GraphObject	getObjectByID(long localId) Gets an identified GraphObject
GraphObjectContainer	getParentContainer() GraphObjectContainer instances can be nested inside of each other by means of the Subgraph class.
GraphObjectContainer	getRootContainer() GraphObjectContainer instances can be nested inside of each other by means of the Subgraph class.
boolean	isDirected() Indicates whether or not the GraphObjectContainer is directed.
boolean	isMultiEdge(Edge edge) Before adding an Edge to the GraphObjectContainer, it might be necessary to find out whether the Edge would be a multiedge.
boolean	isMultiGraph() Querries whether the GraphObjectContainer is a multigraph or not.
void	removeEdge(Edge edge) Removes the given edge from the GraphObjectContainer.
void	removeNode(Node node) Removes the given node from the GraphObjectContainer.
void	setDirected(boolean directed) Changes the fundamental property of the GraphObjectContainer whether it is an undirected or a directed GraphObjectContainer (digraph).
void	setMultiGraph(boolean multigraph) Sets the GraphObjectContainer to be a multigraph or a regular GraphObjectContainer, Multigraphs can have edge (A,B) more than once.

Method Detail

enableGraphEvents

public void enableGraphEvents(int eventmask)

Enables all of the events specified in the given eventmask.

Parameters:

eventmask - specifies which events to enable.

disableGraphEvents

public void disableGraphEvents(int eventmask)

Disables all of the events specified in the given eventmask.

Parameters:

eventmask - specifies which events to disable.

getEventmask

public int getEventmask()

Returns the current event mask of the GraphObjectContainer.

Returns:

the current event mask of the GraphObjectContainer.

enableGraphEventsInternal

public void enableGraphEventsInternal(int eventmaskInternal)

Enables all of the events specified in the given eventmask.

This method is API-Internal. It should never be invoked by clients.

Parameters:

eventmaskInternal - specifies which events to enable.

disableGraphEventsInternal

public void disableGraphEventsInternal(int eventmaskInternal)

Disables all of the events specified in the given eventmask.

This method is API-Internal. It should never be invoked by clients.

Parameters:

eventmaskInternal - specifies which events to disable.

getEventmaskInternal

public int getEventmaskInternal()

Returns the current internal event mask of the GraphObjectContainer.

This method is API-Internal. It should never be invoked by clients.

Returns:

the current internal event mask of the GraphObjectContainer.

getRootContainer

public GraphObjectContainer getRootContainer()

GraphObjectContainer instances can be nested inside of each other by means of the Subgraph class. This method returns the root component of the nesting hierarchy, or the this pointer if this instance is the root of the hierarchy. In case there is no parent assigned then null is returned.

Returns:

the root of the nesting hierarchy or this.

getParentContainer

public GraphObjectContainer getParentContainer()

GraphObjectContainer instances can be nested inside of each other by means of the Subgraph class. This method returns the parent component of this GraphObjectContainer , or null if this instance is the root of the hierarchy.

Returns:

the parent of this instance or null.

getNodeByID

public Node getNodeByID(long localId)

Returns the Node with the given id.

Parameters:

localId - the local id of the Node.

Returns:

the identified Node.

Find more information in the class documentation

getEdgeByID

public Edge getEdgeByID(long localId)

Returns the Edge with the given id.

Parameters:

localId - the local id of the Edge.

Returns:

the identified Edge.

Find more information in the class documentation

getObjectByID

public GraphObject getObjectByID(long localId)

Gets an identified GraphObject

Parameters:

localId - the local id of the GraphObject

Returns:

the identified GraphObject

getNodeCount

public int getNodeCount()

Retrieves the number of nodes from the GraphObjectContainer.

Returns:

the number of nodes in the GraphObjectContainer.

Find more information in the class documentation

getEdgeCount

public int getEdgeCount()

Retrieves the number of edges from the GraphObjectContainer.

Returns:

the number of edges in the GraphObjectContainer.

Find more information in the class documentation

getNodes

public java.util.Iterator getNodes()

Retrieves an Iterator for all nodes.

Returns:

an iterator over all nodes currently in the GraphObjectContainer.

Find more information in the class documentation

getEdges

public java.util.Iterator getEdges()

Retrieves an Iterator for all edges in the GraphObjectContainer.

Returns:

an iterator over all edges currently in the GraphObjectContainer.

Find more information in the class documentation

addNodes

public void addNodes(Node[] nodes)
              throws IllegalNodeException

Convenience method to add several nodes to a GraphObjectContainer in one go. This call will invoke the single addNode() method several times in a row. As soon as a single call to addNode() fails, the adding of any potentially remaining nodes in the array is skipped.

If null is specified as argument to this method then an IllegalNodeException is thrown right away, no events are generated.

Parameters:

nodes - the nodes to add to the GraphObjectContainer.

Throws:

IllegalNodeException - thrown if one of the nodes has an illegal state, or if one of the nodes is in the GraphObjectContainer already. The exception is not thrown if a user veto prevented the adding of the node.

addEdges

public void addEdges(Edge[] edges)
              throws IllegalEdgeException,
                     IllegalNodeException

Convenience method to add several edges to the GraphObjectContainer in one go. This method will invoke the single addEdge() method for each edge that is passed to it.

Parameters:

edges - the edges to add.

Throws:

IllegalEdgeException - thrown if one of the edges is in an illegal state.

IllegalNodeException - thrown if one of the the edges' source or target references point to an illegal node which is not in the GraphObjectContainer or in an invalid state.

addNode

public void addNode(Node node)
             throws IllegalNodeException

Adds the given node to the GraphObjectContainer. If the node can be successfully added a pre-node add event is generated, if that event is not rejected in a vetoable listener then the node-add event is generated. If a node cannot be added at all (e.g. it is already added) then no events are generated at all.

Parameters:

node - the node to add to the GraphObjectContainer.

Throws:

IllegalNodeException - thrown if the node has an illegal state, or if the node is in the GraphObjectContainer already.

Find more information in the class documentation

removeNode

public void removeNode(Node node)
                throws IllegalNodeException

Removes the given node from the GraphObjectContainer. The node must in the GraphObjectContainer for this operation to succeed.

Parameters:

node - the node to remove from the GraphObjectContainer.

Throws:

IllegalNodeException - thrown if the node has an illegal state, or if the node is not in the GraphObjectContainer.

Find more information in the class documentation

addEdge

public void addEdge(Edge edge)
             throws IllegalEdgeException,
                    IllegalNodeException

Adds the given edge to the GraphObjectContainer. The edge must not be in the GraphObjectContainer already and its source and target pointers must point to nodes in the GraphObjectContainer.

Parameters:

edge - the edge to add.

Throws:

IllegalEdgeException - thrown if the edge is in an illegal state.

IllegalNodeException - thrown if the edge's source and target references point to illegal nodes which are not in the GraphObjectContainer or in invalid state.

Find more information in the class documentation

removeEdge

public void removeEdge(Edge edge)
                throws IllegalEdgeException

Removes the given edge from the GraphObjectContainer. The edge must be in the GraphObjectContainer for this operation to succeed.

Parameters:

edge - the edge to remove.

Throws:

IllegalEdgeException - thrown if the edge has in illegal state or if it is not in GraphObjectContainer.

Find more information in the class documentation

isMultiEdge

public boolean isMultiEdge(Edge edge)

Before adding an Edge to the GraphObjectContainer, it might be necessary to find out whether the Edge would be a multiedge.

Parameters:

edge - the Edge to check.

Returns:

true if this edge exists in the GraphObjectContainer already (it is a multiedge). If not then false is returned.

findMultiEdge

public Edge findMultiEdge(Edge edge)

Finds a multi edge for the given edge (the given edge is not added to the GraphObjectContainer at this point in time). null is returned if adding the given edge would not result in a multi-edge GraphObjectContainer. The result of this method is not influenced by the Graph's "Multi-Edge" property (as returned by the method isMultiGraph().

Parameters:

edge - the edge to check for being a multi-edge.

Returns:

the edge that makes the given edge a multi-edge or null if adding the given edge would not result in a multi-edged GraphObjectContainer.

setMultiGraph

public void setMultiGraph(boolean multigraph)
                   throws IllegalGraphException

Sets the GraphObjectContainer to be a multigraph or a regular GraphObjectContainer, Multigraphs can have edge (A,B) more than once. The GraphObjectContainer must be empty to set this property.

Parameters:

multigraph - boolean flag that determines the multigraph property.

Throws:

IllegalGraphException - thrown if the property cannot be set.

isMultiGraph

public boolean isMultiGraph()

Querries whether the GraphObjectContainer is a multigraph or not.

Returns:

true if the GraphObjectContainer is a multigraph otherwise false.

isDirected

public boolean isDirected()

Indicates whether or not the GraphObjectContainer is directed.

Returns:

true if the GraphObjectContainer is a directed GraphObjectContainer.

Find more information in the class documentation

setDirected

public void setDirected(boolean directed)

Changes the fundamental property of the GraphObjectContainer whether it is an undirected or a directed GraphObjectContainer (digraph).

Parameters:

directed - if true the GraphObjectContainer is set to be a directed GraphObjectContainer, otherwise the GraphObjectContainer is made undirected.

buildAdjacencyMatrix

public int[] buildAdjacencyMatrix()
                           throws InappropriateGraphException

Builds the adjacency matrix for this GraphObjectContainer. This operation maybe very expensive. In case it seems too expensive it is up to the implementation to throw an exception.
The diagonal of the matrix is filled with 0 by convention since the graph model does currently not allow to add loop edges.
In case of a multigraph an entry in the matrix represents the number of edges which are connecting the corresponding node pair.

Returns:

the adjacency matrix for this instance.

Throws:

InappropriateGraphException - thrown if the underlying implementation wants to signal that building the adjency matrix is not possible or to expensive

Find more information in the class documentation

getNodeArray

public Node[] getNodeArray()

Returns an array of all nodes, which is suitable for random access.

Returns:

an array of all nodes.

getEdgeArray

public Edge[] getEdgeArray()

Returns an array of all edges, which is suitable for random access.

Returns:

an array of all edges.

fireNodePreRemove

public void fireNodePreRemove(Node node)
                       throws GraphEventVetoException

Fires a fireNodePreRemove event. This method is for internal use only.

Parameters:

node - for internal use only.

Throws:

GraphEventVetoException - thrown if a veto occurred.

fireNodeRemoved

public void fireNodeRemoved(Node node,
                            long previd)

Fires a fireNodeRemoved event. This method is for internal use only.

Parameters:

node - for internal use only.

previd - for internal use only.

firePreEdgeSplitInternal

public void firePreEdgeSplitInternal(Node node,
                                     long oldEdgeID,
                                     Edge oldEdge,
                                     GraphObjectContainer oldEdgeGOC,
                                     Edge newEdge1,
                                     GraphObjectContainer newEdge1GOC,
                                     Edge newEdge2,
                                     GraphObjectContainer newEdge2GOC)
                              throws GraphEventVetoException

Fires a pre-edge split event. This method is for internal use only.

Parameters:

node - for internal use only.

oldEdgeID - for internal use only.

oldEdge - for internal use only.

oldEdgeGOC - for internal use only.

newEdge1 - for internal use only.

newEdge1GOC - for internal use only.

newEdge2 - for internal use only.

newEdge2GOC - for internal use only.

Throws:

GraphEventVetoException - potentially thrown by a vetoable listener.

fireEdgeSplitInternal

public GraphEvent fireEdgeSplitInternal(Node node,
                                        long oldEdgeID,
                                        Edge oldEdge,
                                        GraphObjectContainer oldEdgeGOC,
                                        Edge newEdge1,
                                        GraphObjectContainer newEdge1GOC,
                                        Edge newEdge2,
                                        GraphObjectContainer newEdge2GOC)

Fires an edge split event. This method is for internal use only.

Parameters:

node - for internal use only.

oldEdgeID - for internal use only.

oldEdge - for internal use only.

oldEdgeGOC - for internal use only.

newEdge1 - for internal use only.

newEdge1GOC - for internal use only.

newEdge2 - for internal use only.

newEdge2GOC - for internal use only.

Returns:

the graphevent

firePreCascadeNodeDeleteInternal

public void firePreCascadeNodeDeleteInternal(Node node,
                                             Edge newEdge,
                                             GraphObjectContainer newEdgeGOC,
                                             Edge oldEdge1,
                                             GraphObjectContainer oldEdge1GOC,
                                             Edge oldEdge2,
                                             GraphObjectContainer oldEdge2GOC)
                                      throws GraphEventVetoException

Fires a pre-cascade node delete event. This method is for internal use only.

Parameters:

node - for internal use only.

newEdge - for internal use only.

newEdgeGOC - for internal use only.

oldEdge1 - for internal use only.

oldEdge1GOC - for internal use only.

oldEdge2 - for internal use only.

oldEdge2GOC - for internal use only.

Throws:

GraphEventVetoException - potentially thrown by a vetoable listener.

fireCascadeNodeDeleteInternal

public GraphEvent fireCascadeNodeDeleteInternal(Node node,
                                                Edge newEdge,
                                                GraphObjectContainer newEdgeGOC,
                                                Edge oldEdge1,
                                                GraphObjectContainer oldEdge1GOC,
                                                Edge oldEdge2,
                                                GraphObjectContainer oldEdge2GOC)

Fires a cascade node delete event. This method is for internal use only.

Parameters:

node - for internal use only.

newEdge - for internal use only.

newEdgeGOC - for internal use only.

oldEdge1 - for internal use only.

oldEdge1GOC - for internal use only.

oldEdge2 - for internal use only.

oldEdge2GOC - for internal use only.

Returns:

the graphevent