i3.dragos.gm.core
Interface GraphEntity

All Superinterfaces:

ExistenceCheckable, MetaAttributable

All Known Subinterfaces:

Edge, Graph, Node, Relation, RelationEnd

All Known Implementing Classes:

EdgeProxy, GraphEntityProxy, GraphProxy, NodeProxy, RelationEndProxy, RelationProxy

public interface GraphEntity
extends MetaAttributable, ExistenceCheckable

GraphEntity is the base class of all graphs, edges, nodes, relations and relation ends.

Author:

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

See Also:

Core Graph Model, Implementation Issues

Method Summary

boolean	equals(java.lang.Object o) Checks for equality with another object.
java.util.Collection<? extends GraphEntity>	getAdjacentGraphEntities(ConnectionMode connectionMode, EdgeClass type, boolean includeSubClasses) Returns all adjacent graph entities connected through Edges.
java.util.Collection<? extends Relation>	getAdjacentRelations(ConnectionMode connectionMode, RelationClass type, boolean includeSubClasses) Returns all adjacent Relations connected through RelationEnds.
java.util.Collection<? extends Relation>	getAdjacentRelations(ConnectionMode connectionMode, RelationEndClass type, boolean includeSubClasses) Returns all adjacent Relations connected through RelationEnds.
java.util.Map<Attribute,java.io.Serializable>	getAllValidAttributeValues() Returns a map containg all attributes which have a valid value at the moment.
java.io.Serializable	getAttributeValue(Attribute attribute) Returns the value of the attribute.
DataSourceURL	getDataSourceURL() Returns the URL to the data source that stores this graph entity.
java.util.Collection<? extends Edge>	getEdges(ConnectionMode connectionMode) Returns a collection containing the (Edge) of all edges of the requested kind connected to this graph element.
java.util.Collection<? extends Edge>	getEdges(ConnectionMode connectionMode, EdgeClass type, boolean includeSubClasses) Returns a collection containing the (Edge) of all edges of the requested kind and type connected to this graph element.
GraphEntityClass	getGraphEntityClass() Returns the graph entity's type.
java.io.Serializable	getInternalIdentifier() Returns the internal identifier used to uniquely identify this object in the storage backend.
Graph	getParent() Returns the graph this graph element is contained in.
java.util.Collection<? extends RelationEnd>	getRelationEnds(ConnectionMode connectionMode) Returns a collection containing all relation ends of the requested kind connected to this graph element.
java.util.Collection<? extends RelationEnd>	getRelationEnds(ConnectionMode connectionMode, RelationClass type, boolean includeSubClasses) Returns a collection containing all relation ends of the requested kind and type connected to this graph element.
java.util.Collection<? extends RelationEnd>	getRelationEnds(ConnectionMode connectionMode, RelationEndClass type, boolean includeSubClasses) Returns a collection containing all relation ends of the requested kind and type connected to this graph element.
GraphEntity	getWrappedGraphEntity() Returns the wrapped entity, null if none.
int	hashCode() To comply with the general contract for Object.hashCode(), it is recommended to return the hash code of the internal identifier.
boolean	isAttributeValid(Attribute attribute) Returns true if the attribute's value is valid and false otherwise.
boolean	isIncident(Edge edge) Returns true if the specified edge is connected to this graph element and false otherwise.
boolean	isIncident(RelationEnd relationEnd) Returns true if the specified relation end is connected to this graph element and false otherwise.
void	putAttributeValue(Attribute attribute, java.io.Serializable value) Stores a new value for the attribute and sets its validity to true.
void	setAttributeInvalid(Attribute attribute) Marks an attribute's value as invalid.

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

equals

boolean equals(java.lang.Object o)

Checks for equality with another object.

This object is considered equal if all of the following conditions are met:

• o != null
• o instanceof GraphEntity
• getDataSourceURL().equals(((GraphEntity) o).getDataSourceURL())
• getInternalIdentifier().equals(((GraphEntity) o).getInternalIdentifier())

Subclasses and implementations might want to extend this list by adding assertions comparing additional or internal data (e.g. the type of the graph entity). However, equality must only be determined by the above rules, preferably by using super.equals(o), and any difference in the additional data for two object equal according to the rules above is to be considered an error.

Overrides:

equals in class java.lang.Object

Parameters:

o - The Object to compare to.

Returns:

true if o is equal according to above rules, false otherwise.

hashCode

int hashCode()

To comply with the general contract for Object.hashCode(), it is recommended to return the hash code of the internal identifier.

Overrides:

hashCode in class java.lang.Object

Returns:

The hash code.

getDataSourceURL

DataSourceURL getDataSourceURL()

Returns the URL to the data source that stores this graph entity. The returned value is guaranteed to not be null.

Returns:

the URL to the data source that stores the graph entity.

getInternalIdentifier

java.io.Serializable getInternalIdentifier()

Returns the internal identifier used to uniquely identify this object in the storage backend.

To retrieve the entity use GraphPool.getGraphEntityByInternalIdentifier(Serializable). As alternative you may consider to use the classes in the package i3.dragos.gm.core.id.

Returns:

the internal identifier.

getGraphEntityClass

GraphEntityClass getGraphEntityClass()
                                     throws DragosException

Returns the graph entity's type. Since all graph entities are typed, this is never null.

Returns:

The graph entity's type.

Throws:

DragosException - if something went wrong.

getParent

Graph getParent()
                throws DragosException

Returns the graph this graph element is contained in. This may be null for and only for top-level graphs.

Returns:

the graph this graph element is contained in.

Throws:

DragosException - if something went wrong.

putAttributeValue

void putAttributeValue(Attribute attribute,
                       java.io.Serializable value)
                       throws EntityNotFoundException,
                              DragosException,
                              java.lang.IllegalArgumentException

Stores a new value for the attribute and sets its validity to true.

Parameters:

attribute - The attribute.

value - The new value of the attribute. May be null.

Throws:

java.lang.IllegalArgumentException - if id is null or does not match the attribute's value Java class type.

EntityNotFoundException - if the attribute is not defined for this entity.

DragosException - if something went wrong.

getAttributeValue

java.io.Serializable getAttributeValue(Attribute attribute)
                                       throws EntityNotFoundException,
                                              InvalidValueException,
                                              DragosException

Returns the value of the attribute. The value of the attribute may be null.

The check whether the attribute is defined for this entity's class (which might result in an EntityNotFoundException) has to be performed every time, even when the non-existance of such an attribute in the implementations attribute map already would be sufficient to throw an InvalidValueException!

In other words: check the Attribute first, before trying to look up the value.
This ensures conistency with the other attribute handling methods and helps detect user errors.

Parameters:

attribute - The attribute that should be retrieved.

Returns:

The value of the attribute.

Throws:

java.lang.IllegalArgumentException - if id is null.

EntityNotFoundException - if the attribute is not defined stored for this entity.

InvalidValueException - if the value of the attribute is not valid (explicitly marked invalid or not set yet).

DragosException - if something went wrong.

getAllValidAttributeValues

java.util.Map<Attribute,java.io.Serializable> getAllValidAttributeValues()
                                                                         throws DragosException

Returns a map containg all attributes which have a valid value at the moment. The elements in the map are of type Attribute, Object}.

Returns:

a map containg all attributes which have a valid value at the moment.

Throws:

DragosException - if something went wrong.

setAttributeInvalid

void setAttributeInvalid(Attribute attribute)
                         throws EntityNotFoundException,
                                DragosException

Marks an attribute's value as invalid.

The check whether this Attribute is defined for this entity's class (which might result in an EntityNotFoundException) has to be performed every time, even when the non-existance of such an attribute in the implementations attribute map already would be sufficient return without above check, since the attribute obviously must be invalid already!
This ensures conistency with the other attribute handling methods and helps detect user errors.

Parameters:

attribute - The attribute.

Throws:

java.lang.IllegalArgumentException - if id is null.

EntityNotFoundException - if this attribute is not defined for this entity.

DragosException - if something went wrong.

isAttributeValid

boolean isAttributeValid(Attribute attribute)
                         throws EntityNotFoundException,
                                DragosException

Returns true if the attribute's value is valid and false otherwise.

The check whether this Attribute is defined for this entity's class (which might result in an EntityNotFoundException) has to be performed every time, even when the non-existance of such an attribute in the implementations attribute map already would be sufficient to return false without above check!
This ensures conistency with the other attribute handling methods and helps detect user errors.

Parameters:

attribute - The attribute.

Returns:

true if the attribute's value is valid and false otherwise.

Throws:

java.lang.IllegalArgumentException - if id is null.

EntityNotFoundException - if this attribute is not defined for this entity.

DragosException - if something went wrong.

getEdges

java.util.Collection<? extends Edge> getEdges(ConnectionMode connectionMode)
                                              throws DragosException

Returns a collection containing the (Edge) of all edges of the requested kind connected to this graph element.

Parameters:

connectionMode - The kind of edges that should be returned.

Returns:

a collection containing the (Edge) of all edges of the requested kind connected to this graph element.

Throws:

DragosException - if something went wrong.

getEdges

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

Returns a collection containing the (Edge) of all edges of the requested kind and type connected to this graph element.

Parameters:

connectionMode - The kind of edges that should be returned.

type - The type of edges wanted (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 (ignored if type == null).

Returns:

a collection containing the (Edge) of all edges of the requested kind and type connected to this graph element.

Throws:

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

DragosException - if something went wrong.

isIncident

boolean isIncident(Edge edge)
                   throws DragosException

Returns true if the specified edge is connected to this graph element and false otherwise.

Parameters:

edge - The edge, which will be checked.

Returns:

true if the specified edge is connected to this graph element and false otherwise.

Throws:

DragosException - if something went wrong.

getAdjacentGraphEntities

java.util.Collection<? extends GraphEntity> getAdjacentGraphEntities(ConnectionMode connectionMode,
                                                                     EdgeClass type,
                                                                     boolean includeSubClasses)
                                                                     throws EntityNotFoundException,
                                                                            DanglingReferenceException,
                                                                            DragosException

Returns all adjacent graph entities connected through Edges. The returned Collection contains the requested adjacent entities.

Parameters:

connectionMode - The kind of edges that should be followed.

type - The type of edges to follow (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 (ignored if type == null).

Returns:

a collection containing the requested adjacent entities.

Throws:

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

DanglingReferenceException - if this method would have to traverse a dangling edge.

DragosException - if something went wrong.

getRelationEnds

java.util.Collection<? extends RelationEnd> getRelationEnds(ConnectionMode connectionMode)
                                                            throws DragosException

Returns a collection containing all relation ends of the requested kind connected to this graph element.

"Connected" means that this graph entity is the "relatedElement" of the relation end. This implies that, if this method is called on a relation, relation ends belonging to the relation will only be returned if they point back to it. To access all dependent relation ends of a relation, see Relation.getAllRelationEndsOfRelation().

Parameters:

connectionMode - The kind of relation ends that should be returned.

Returns:

a collection containing all relation ends of the requested kind connected to this graph element.

Throws:

DragosException - if something went wrong.

getRelationEnds

java.util.Collection<? extends RelationEnd> getRelationEnds(ConnectionMode connectionMode,
                                                            RelationClass type,
                                                            boolean includeSubClasses)
                                                            throws EntityNotFoundException,
                                                                   DragosException

Returns a collection containing all relation ends of the requested kind and type connected to this graph element.

"Connected" means that this graph entity is the "relatedElement" of the relation end. This implies that, if this method is called on a relation, relation ends belonging to the relation will only be returned if they point back to it. To access all dependent relation ends of a relation, see Relation.getAllRelationEndsOfRelation().

Parameters:

connectionMode - The kind of relation ends that should be returned.

type - The type of the relation the relation end belongs to (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 (ignored if type == null).

Returns:

a collection containing all relations of the requested kind and type connected to this graph element.

Throws:

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

DragosException - if something went wrong.

getRelationEnds

java.util.Collection<? extends RelationEnd> getRelationEnds(ConnectionMode connectionMode,
                                                            RelationEndClass type,
                                                            boolean includeSubClasses)
                                                            throws EntityNotFoundException,
                                                                   DragosException

Returns a collection containing all relation ends of the requested kind and type connected to this graph element.

"Connected" means that this graph entity is the "relatedElement" of the relation end. This implies that, if this method is called on a relation, relation ends belonging to the relation will only be returned if they point back to it. To access all dependent relation ends of a relation, see Relation.getAllRelationEndsOfRelation().

Parameters:

connectionMode - The kind of relation ends that should be returned.

type - The type the relation ends have to belong to (null means "any type").

includeSubClasses - If and only if true, this method will also match relation ends whose RelationEndClass is a subclass of the specified type (ignored if type == null).

Returns:

a collection containing all relations of the requested kind and type connected to this graph element.

Throws:

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

DragosException - if something went wrong.

isIncident

boolean isIncident(RelationEnd relationEnd)
                   throws DragosException

Returns true if the specified relation end is connected to this graph element and false otherwise.

Parameters:

relationEnd - The relationEnd, which will be checked.

Returns:

true if the specified relationEnd is connected to this graph element and false otherwise.

Throws:

DragosException - if something went wrong.

getAdjacentRelations

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

Returns all adjacent Relations connected through RelationEnds.

As with getRelationEnds(ConnectionMode), "connected" means that this graph entity is the "relatedElement" of the relation end. This implies that, if this method is called on a relation, relation ends belonging to the relation will only be returned if they point back to it.

For accessing the dependent relation ends of a relation, or the entities connected through those, there are a number of methods in Relation.

Parameters:

connectionMode - The kind of relation ends that should be followed.

type - The type of Relations whose RelationEnds we should follow (null means "any type").

includeSubClasses - If and only if true, this method will also follow relation ends belonging to instances of subclasses of the specified RelationClass (ignored if type == null).

Returns:

a collection containing the requested adjacent entities.

Throws:

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

DragosException - if something went wrong.

getAdjacentRelations

java.util.Collection<? extends Relation> getAdjacentRelations(ConnectionMode connectionMode,
                                                              RelationEndClass type,
                                                              boolean includeSubClasses)
                                                              throws EntityNotFoundException,
                                                                     DragosException

Returns all adjacent Relations connected through RelationEnds.

As with getRelationEnds(ConnectionMode), "connected" means that this graph entity is the "relatedElement" of the relation end. This implies that, if this method is called on a relation, relation ends belonging to the relation will only be returned if they point back to it.

For accessing the dependent relation ends of a relation, or the entities connected through those, there are a number of methods in Relation.

Parameters:

connectionMode - The kind of relation ends that should be followed.

type - The type of RelationEnds we should follow (null means "any type").

includeSubClasses - If and only if true, this method will also follow relation ends whose RelationEndClass is a subclass of the specified type (ignored if type == null).

Returns:

a collection containing the requested adjacent entities.

Throws:

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

DragosException - if something went wrong.

getWrappedGraphEntity

GraphEntity getWrappedGraphEntity()

Returns the wrapped entity, null if none. For subinterfaces defined in the core GM (like Edge, Node...), the returned value is guaranteed to be an instance of the same subinterface.

Returns:

the wrapped entity, null if none.