i3.dragos.gm.core
Interface Graph

All Superinterfaces:

ExistenceCheckable, GraphEntity, MetaAttributable

All Known Implementing Classes:

GraphProxy

public interface Graph
extends GraphEntity

The Graph interface offers access to the graph and its sub graphs.

Only top-level graphs (those without a parent) have a name (!= null), For all other graphs it must be null. Thus, the following condition always holds:

           (hasParent() and (name == null))
    or (not hasParent() and (name != null))
  

All methods taking GraphEntitys as parameters only work on graph elements directly contained in this graph, and throw an exception if this graph is not the element's parent (as determined by GraphEntity.getParent()).

Author:

Peter Kehren, Boris Boehlen <boehlen@cs.rwth-aachen.de>, Thorsten Hermes <thermes@i3.informatik.rwth-aachen.de>

See Also:

Core Graph Model, Implementation Issues

Method Summary

void	clear() Removes everything in the graph.
boolean	contains(GraphEntity ge) Returns true if the specified graph element is in the graph.
Edge	createEdge(GraphEntity source, GraphEntity target, EdgeClass type) Creates a new edge between the specified source and target graph element, which will belong to this graph and returns it.
Graph	createGraph(GraphClass type) Creates a new graph, which will belong to this graph, and returns it.
Node	createNode(NodeClass type) Creates a new node, which will belong to this graph and returns it.
Relation	createRelation(RelationClass type) Creates a new relation, which will belong to this graph and returns it.
java.util.Collection<? extends Edge>	getAllEdgesOfGraph() Returns a collection containing all edges stored in the graph.
java.util.Collection<? extends Edge>	getAllEdgesOfGraph(EdgeClass type, boolean includeSubClasses) Returns a collection containing all edges of the specified type stored in the graph.
java.util.Collection<? extends GraphEntity>	getAllGraphEntitiesOfGraph() Returns a collection containing all graph entities stored in the graph.
java.util.Collection<? extends GraphEntity>	getAllGraphEntitiesOfGraph(GraphEntityClass type, boolean includeSubClasses) Returns a collection containing all graph entities of the specified type stored in the graph.
java.util.Collection<? extends Graph>	getAllGraphsOfGraph() Returns a collection containing all graphs stored in the graph.
java.util.Collection<? extends Graph>	getAllGraphsOfGraph(GraphClass type, boolean includeSubClasses) Returns a collection containing the graphs of the specified type stored in the graph.
java.util.Collection<? extends Node>	getAllNodesOfGraph() Returns a collection containing all nodes stored in the graph.
java.util.Collection<? extends Node>	getAllNodesOfGraph(NodeClass type, boolean includeSubClasses) Returns a collection containing all nodes of the specified type stored in the graph.
java.util.Collection<? extends Relation>	getAllRelationsOfGraph() Returns a collection containing all relations stored in the graph.
java.util.Collection<? extends Relation>	getAllRelationsOfGraph(RelationClass type, boolean includeSubClasses) Returns a collection containing all relations of the specified type stored in the graph.
GraphClass	getGraphClass() Returns the type of the graph.
java.util.Collection<? extends GraphEntity>	getGraphEntitiesByAttributeValue(Attribute attribute, java.io.Serializable value) Returns a collection of graph elements (GraphEntity) which have the requested value for the attribute.
java.lang.String	getName() Returns the name of the graph.
boolean	hasParent() Returns true if the graph is contained in another graph, false otherwise.
boolean	isEmpty() Returns true if not even a single graph element (graph, node, edge, etc) is contained in the graph.
void	removeAllEdges() Removes all edges froms the graph.
void	removeAllEdges(EdgeClass type, boolean includeSubClasses) Removes all edges of the specified type from the graph.
void	removeAllGraphs() Removes all graphs froms the graph.
void	removeAllGraphs(GraphClass type, boolean includeSubClasses) Removes all graphs of the specified type from the graph.
void	removeAllNodes() Removes all nodes froms the graph.
void	removeAllNodes(NodeClass type, boolean includeSubClasses) Removes all nodes of the specified type from the graph.
void	removeAllRelations() Removes all relations froms the graph.
void	removeAllRelations(RelationClass type, boolean includeSubClasses) Removes all relations of the specified type from the graph.
void	removeGraphEntity(GraphEntity graphEntity) Removes the graph entity from this graph.

Methods inherited from interface i3.dragos.gm.core.GraphEntity

equals, getAdjacentGraphEntities, getAdjacentRelations, getAdjacentRelations, getAllValidAttributeValues, getAttributeValue, getDataSourceURL, getEdges, getEdges, getGraphEntityClass, getInternalIdentifier, getParent, getRelationEnds, getRelationEnds, getRelationEnds, getWrappedGraphEntity, hashCode, isAttributeValid, isIncident, isIncident, putAttributeValue, setAttributeInvalid

Methods inherited from interface i3.dragos.gm.core.schema.MetaAttributable

getAllMetaAttributes, getMetaAttribute, isMetaAttributeKeyReserved, isMetaAttributeSet, setMetaAttribute, unsetMetaAttribute

Methods inherited from interface i3.dragos.gm.core.schema.ExistenceCheckable

checkExistence, checkExistenceOptional

Method Detail

getGraphClass

GraphClass getGraphClass()
                         throws DragosException

Returns the type of the graph.

Returns:

the GraphClass.

Throws:

DragosException - if something went wrong.

getName

java.lang.String getName()

Returns the name of the graph. For non top-level graphs null is always returned.

Returns:

the name of the graph.

hasParent

boolean hasParent()
                  throws DragosException

Returns true if the graph is contained in another graph, false otherwise.

Returns:

true if the graph is contained in another graph, false otherwise.

Throws:

DragosException - if something went wrong.

isEmpty

boolean isEmpty()
                throws DragosException

Returns true if not even a single graph element (graph, node, edge, etc) is contained in the graph.

Returns:

true if the graph is empty, false otherwise.

Throws:

DragosException - if something went wrong.

clear

void clear()
           throws DragosException

Removes everything in the graph.

Note: This method follows the same rules as the methods for removing edges, nodes, graphs and relations individually!

Throws:

DragosException - if something went wrong.

contains

boolean contains(GraphEntity ge)
                 throws DragosException

Returns true if the specified graph element is in the graph.

Parameters:

ge - The requested graph element (must not be null).

Returns:

true if the graph element is contained in the graph and false otherwise.

Throws:

DragosException - if anything went wrong.

removeGraphEntity

void removeGraphEntity(GraphEntity graphEntity)
                       throws EntityNotFoundException,
                              DragosException

Removes the graph entity from this graph.

Deletion proceeds as follows:

1. All relation ends connected to the graph entity (as determined by GraphEntity.getRelationEnds(ConnectionMode) using ConnectionMode.ANY_SET as parameter) are removed.
2. All edges connected to the graph entity are removed.
3. If the entity to remove is a Graph, it will be cleared using clear().
4. If the entity to remove is a Relation, all its RelationEnds are removed using Relation.removeAllRelationEndsOfRelation().
5. All attributes are removed.
6. All meta attributes are removed.
7. The entity itself is deleted.

Implementation notice: Some edges and relation ends might already be deleted due to cascading removal of entities processed before, so take care when iterating through the instances.

Parameters:

graphEntity - The graph, which shall be deleted.

Throws:

EntityNotFoundException - if the graph entity could not be found in the graph.

DragosException - if something else went wrong.

getAllGraphEntitiesOfGraph

java.util.Collection<? extends GraphEntity> getAllGraphEntitiesOfGraph()
                                                                       throws DragosException

Returns a collection containing all graph entities stored in the graph.

Returns:

A collection containing the all graph entities contained in the graph (ignoring sub graphs).

Throws:

DragosException - if anything went wrong.

getAllGraphEntitiesOfGraph

java.util.Collection<? extends GraphEntity> getAllGraphEntitiesOfGraph(GraphEntityClass type,
                                                                       boolean includeSubClasses)
                                                                       throws EntityNotFoundException,
                                                                              DragosException

Returns a collection containing all graph entities of the specified type stored in the graph.

Parameters:

type - The type of the edges (null means "any type").

includeSubClasses - If and only if true, this method will also match graph entities whose GraphEntityClass is a subclass of the specified type.

Returns:

A collection containing all graph entities of the specified type contained in the graph (ignoring sub graphs).

Throws:

EntityNotFoundException - if the requested type could not be found.

DragosException - if anything went wrong.

createGraph

Graph createGraph(GraphClass type)
                  throws EntityNotFoundException,
                         GraphEntityInstantiationException,
                         DragosException,
                         java.lang.IllegalArgumentException

Creates a new graph, which will belong to this graph, and returns it. The graph will have the requested type.

Since graphs created in other graphs are not top-level graphs, their name will be null by definition.

Parameters:

type - The graph's type.

Returns:

the new graph which is a sub-graph of this one.

Throws:

EntityNotFoundException - if the type for the graph couldn't be found.

java.lang.IllegalArgumentException - if type is null.

GraphEntityInstantiationException - if type is declared as an abstract class.

DragosException - if something else went wrong.

removeAllGraphs

void removeAllGraphs(GraphClass type,
                     boolean includeSubClasses)
                     throws EntityNotFoundException,
                            DragosException

Removes all graphs of the specified type from the graph. See removeGraphEntity(GraphEntity) for details.

Parameters:

type - The type of the graphs to be deleted (null means "any type").

includeSubClasses - If and only if true, this method will also match graphs whose graph class is a subclass of the specified type.

Throws:

EntityNotFoundException - if the type could not be found.

DragosException - if something else went wrong.

removeAllGraphs

void removeAllGraphs()
                     throws DragosException

Removes all graphs froms the graph. See removeGraphEntity(GraphEntity) for details.

Throws:

DragosException - if anything went wrong.

getAllGraphsOfGraph

java.util.Collection<? extends Graph> getAllGraphsOfGraph(GraphClass type,
                                                          boolean includeSubClasses)
                                                          throws EntityNotFoundException,
                                                                 DragosException

Returns a collection containing the graphs of the specified type stored in the graph.

Parameters:

type - The type of the graphs (null means "any type").

includeSubClasses - If and only if true, this method will also match graphs whose GraphClass is a subclass of the specified type.

Returns:

A collection containing all graphs of the specified type contained in the graph (ignoring sub graphs).

Throws:

EntityNotFoundException - if the requested type could not be found.

DragosException - if anything went wrong.

getAllGraphsOfGraph

java.util.Collection<? extends Graph> getAllGraphsOfGraph()
                                                          throws DragosException

Returns a collection containing all graphs stored in the graph.

Returns:

A collection containing all graphs contained in the graph (ignoring sub graphs).

Throws:

DragosException - if anything went wrong.

createNode

Node createNode(NodeClass type)
                throws EntityNotFoundException,
                       GraphEntityInstantiationException,
                       DragosException,
                       java.lang.IllegalArgumentException

Creates a new node, which will belong to this graph and returns it. The node will have the requested type.

Parameters:

type - The type of the new node.

Returns:

the new node.

Throws:

EntityNotFoundException - if the type for the node couldn't be found.

java.lang.IllegalArgumentException - if type is null.

GraphEntityInstantiationException - if type is declared as an abstract class.

DragosException - if something else went wrong.

removeAllNodes

void removeAllNodes(NodeClass type,
                    boolean includeSubClasses)
                    throws EntityNotFoundException,
                           DragosException

Removes all nodes of the specified type from the graph. See removeGraphEntity(GraphEntity) for details.

Parameters:

type - The type of the nodes to be deleted (null means "any type").

includeSubClasses - If and only if true, this method will also match nodes whose NodeClass is a subclass of the specified type.

Throws:

EntityNotFoundException - if the type could not be found.

DragosException - if something else went wrong.

removeAllNodes

void removeAllNodes()
                    throws EntityInUseException,
                           DragosException

Removes all nodes froms the graph. See removeGraphEntity(GraphEntity) for details.

Throws:

DragosException - if anything went wrong.

EntityInUseException - if one of the nodes is in use.

getAllNodesOfGraph

java.util.Collection<? extends Node> getAllNodesOfGraph(NodeClass type,
                                                        boolean includeSubClasses)
                                                        throws EntityNotFoundException,
                                                               DragosException

Returns a collection containing all nodes of the specified type stored in the graph.

Parameters:

type - The type of the nodes (null means "any type").

includeSubClasses - If and only if true, this method will also match nodes whose NodeClass is a subclass of the specified type.

Returns:

A collection containing the all nodes of the specified type contained in the graph (ignoring sub graphs).

Throws:

EntityNotFoundException - if the requested type could not be found.

DragosException - if anything went wrong.

getAllNodesOfGraph

java.util.Collection<? extends Node> getAllNodesOfGraph()
                                                        throws DragosException

Returns a collection containing all nodes stored in the graph.

Returns:

A collection containing the all nodes contained in the graph (ignoring sub graphs).

Throws:

DragosException - if anything went wrong.

createEdge

Edge createEdge(GraphEntity source,
                GraphEntity target,
                EdgeClass type)
                throws EntityNotFoundException,
                       GraphEntityInstantiationException,
                       DragosException,
                       java.lang.IllegalArgumentException

Creates a new edge between the specified source and target graph element, which will belong to this graph and returns it. The edge will have the requested type. Source and target may be contained in any graph, as long as they are in the same graph pool as this graph.

Parameters:

source - The source graph element of the edge (may be null).

target - The target graph element of the edge (may be null).

type - The type of the new edge (must not be null).

Returns:

the new edge.

Throws:

EntityNotFoundException - if the source or the target were not null and could not be found, or if the type for the edge could not be found.

java.lang.IllegalArgumentException - if type is null.

GraphEntityInstantiationException - if type is declared as an abstract class.

DragosException - if something else went wrong.

removeAllEdges

void removeAllEdges(EdgeClass type,
                    boolean includeSubClasses)
                    throws EntityNotFoundException,
                           DragosException

Removes all edges of the specified type from the graph. See removeGraphEntity(GraphEntity) for details.

Parameters:

type - The type of the edges to be deleted (null means "any type").

includeSubClasses - If and only if true, this method will also match edges whose EdgeClass is a subclass of the specified type.

Throws:

EntityNotFoundException - if the type could not be found.

DragosException - if something else went wrong.

removeAllEdges

void removeAllEdges()
                    throws EntityInUseException,
                           DragosException

Removes all edges froms the graph. See removeGraphEntity(GraphEntity) for details.

Throws:

DragosException - if anything went wrong.

EntityInUseException - if one of the edges is in use.

getAllEdgesOfGraph

java.util.Collection<? extends Edge> getAllEdgesOfGraph(EdgeClass type,
                                                        boolean includeSubClasses)
                                                        throws EntityNotFoundException,
                                                               DragosException

Returns a collection containing all edges of the specified type stored in the graph.

Parameters:

type - The type of the edges (null means "any type").

includeSubClasses - If and only if true, this method will also match edges whose EdgeClass is a subclass of the specified type.

Returns:

A collection containing all edges of the specified type contained in the graph (ignoring sub graphs).

Throws:

EntityNotFoundException - if the requested type could not be found.

DragosException - if anything went wrong.

getAllEdgesOfGraph

java.util.Collection<? extends Edge> getAllEdgesOfGraph()
                                                        throws DragosException

Returns a collection containing all edges stored in the graph.

Returns:

A collection containing all edges contained in the graph (ignoring sub graphs).

Throws:

DragosException - if anything went wrong.

createRelation

Relation createRelation(RelationClass type)
                        throws EntityNotFoundException,
                               GraphEntityInstantiationException,
                               DragosException,
                               java.lang.IllegalArgumentException

Creates a new relation, which will belong to this graph and returns it. The relation will have the requested type.

Parameters:

type - The type of the new relation.

Returns:

the new relation.

Throws:

EntityNotFoundException - if the type for the relation couldn't be found.

java.lang.IllegalArgumentException - if type is null.

GraphEntityInstantiationException - if type is declared as an abstract class.

DragosException - if something else went wrong.

removeAllRelations

void removeAllRelations(RelationClass type,
                        boolean includeSubClasses)
                        throws EntityNotFoundException,
                               DragosException

Removes all relations of the specified type from the graph. See removeGraphEntity(GraphEntity) for details.

Parameters:

type - The type of the relations to be deleted (null means "any type").

includeSubClasses - If and only if true, this method will also match relations whose RelationClass is a subclass of the specified type.

Throws:

EntityNotFoundException - if the type could not be found.

DragosException - if something else went wrong.

removeAllRelations

void removeAllRelations()
                        throws EntityInUseException,
                               DragosException

Removes all relations froms the graph. See removeGraphEntity(GraphEntity) for details.

Throws:

DragosException - if anything went wrong.

EntityInUseException - if one of the edges is in use.

getAllRelationsOfGraph

java.util.Collection<? extends Relation> getAllRelationsOfGraph(RelationClass type,
                                                                boolean includeSubClasses)
                                                                throws EntityNotFoundException,
                                                                       DragosException

Returns a collection containing all relations of the specified type stored in the graph.

Parameters:

type - The type of the relations (null means "any type").

includeSubClasses - If and only if true, this method will also match relations whose RelationClass is a subclass of the specified type.

Returns:

A collection containing all relations of the specified type contained in the graph (ignoring sub graphs).

Throws:

EntityNotFoundException - if the requested type could not be found.

DragosException - if anything went wrong.

getAllRelationsOfGraph

java.util.Collection<? extends Relation> getAllRelationsOfGraph()
                                                                throws DragosException

Returns a collection containing all relations stored in the graph.

Returns:

A collection containing all relations contained in the graph (ignoring sub graphs).

Throws:

DragosException - if anything went wrong.

getGraphEntitiesByAttributeValue

java.util.Collection<? extends GraphEntity> getGraphEntitiesByAttributeValue(Attribute attribute,
                                                                             java.io.Serializable value)
                                                                             throws EntityNotFoundException,
                                                                                    DragosException

Returns a collection of graph elements (GraphEntity) which have the requested value for the attribute.

Parameters:

attribute - The attribute.

value - The requested value. May be null.

Returns:

collection of graph elements (GraphEntity) which have the requested value for the attribute.

Throws:

EntityNotFoundException - if the attribute could not be found.

DragosException - if anything went wrong.