i3.dragos.gm.core
Interface Relation

All Superinterfaces:

ExistenceCheckable, GraphEntity, MetaAttributable

All Known Implementing Classes:

RelationProxy

public interface Relation
extends GraphEntity

The Relation interface represents a n-ary relation (hyper edges) connected to multiple graph elements.

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

RelationEnd	createRelationEnd(GraphEntity target, RelationEndClass type) Creates a relation end.
java.util.Collection<? extends RelationEnd>	getAllRelationEndsOfRelation() Returns a collection of all relation ends of this relation.
java.util.Collection<? extends GraphEntity>	getRelatedGraphEntitiesOfRelationEndsOfRelation(RelationEndClass type, boolean includeSubClasses, boolean set) Returns a collection of entities referenced by this relation through relation ends.
RelationClass	getRelationClass() Returns the relation's type.
java.util.Collection<? extends RelationEnd>	getRelationEndsOfRelation(RelationEndClass type, boolean includeSubClasses) Returns a collection of all relation ends of the specified type belonging to this relation.
boolean	isDirected() Returns true if the relation is directed and false otherwise.
void	removeAllRelationEndsOfRelation() Removes all relation ends belonging to this relation from it.
void	removeRelationEnd(RelationEnd relationEnd) Removes a relation end belonging to this relation from it.

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

getRelationClass

RelationClass getRelationClass()
                               throws DragosException

Returns the relation's type.

Returns:

the relation's type.

Throws:

DragosException - if something went wrong.

isDirected

boolean isDirected()
                   throws DragosException

Returns true if the relation is directed and false otherwise.

A relation is directed if it contains at least one directed relation end. If all contained relation ends are undirected the relation is undirected, too.

Returns:

true if the relation is directed and false otherwise.

Throws:

DragosException - if something went wrong.

createRelationEnd

RelationEnd createRelationEnd(GraphEntity target,
                              RelationEndClass type)
                              throws DragosException

Creates a relation end.

The target (if not null)) has to be in the same graph pool as this relation, otherwise an exception is thrown.

Parameters:

target - The graph element the relation end is connected to (may be null).

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

Returns:

the new relation end.

Throws:

EntityNotFoundException - if the target was not null and could not be found, or if the type for the relation end could not be found.

java.lang.IllegalArgumentException - if any argument value is illegal.

DragosException - if something else went wrong.

removeRelationEnd

void removeRelationEnd(RelationEnd relationEnd)
                       throws EntityNotFoundException,
                              DragosException

Removes a relation end belonging to this relation from it.

It simply performs an additional check whether the RelationEnd to remove really belongs to this Relation, throwing an EntityNotFoundException if not. Afterwards, it follows the same procedure as Graph.removeGraphEntity(GraphEntity).

This method could/should be implemented roughly as follows:

 if (! this.equals(relationEnd.getRelation())) {
     throw new EntityNotFoundException("RelationEnd " + relationEnd + " does not belong to " + toString());
 }
 getParent().removeGraphEntity(relationEnd);
 

Parameters:

relationEnd - the relation end which is removed.

Throws:

EntityNotFoundException - if the relation end couldn't be found or does not belong to this relation.

DragosException - if something went wrong.

removeAllRelationEndsOfRelation

void removeAllRelationEndsOfRelation()
                                     throws DragosException

Removes all relation ends belonging to this relation from it. It follows the same rules as Graph.removeGraphEntity(GraphEntity), and could / should be implemented using that method.

Relation ends connected to the relation, but not belongig to it, are not affected.

Throws:

DragosException - if something went wrong .

getAllRelationEndsOfRelation

java.util.Collection<? extends RelationEnd> getAllRelationEndsOfRelation()
                                                                         throws DragosException

Returns a collection of all relation ends of this relation. The contents of the returned collection will be of type RelationEnd.

Returns:

A collection of all relation ends.

Throws:

DragosException - if anything went wrong.

getRelationEndsOfRelation

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

Returns a collection of all relation ends of the specified type belonging to this relation.

If type == null, this method is equivalent to getAllRelationEndsOfRelation().

Parameters:

type - The type of the relation ends to return (null means "any type").

includeSubClasses - Whether instances of subclasses of type should also be returned (has no effect if type == null).

Returns:

A collection of all relation ends.

Throws:

EntityNotFoundException - if type != null and type is not a dependent relation end class of relation's class.

DragosException - if anything went wrong.

getRelatedGraphEntitiesOfRelationEndsOfRelation

java.util.Collection<? extends GraphEntity> getRelatedGraphEntitiesOfRelationEndsOfRelation(RelationEndClass type,
                                                                                            boolean includeSubClasses,
                                                                                            boolean set)
                                                                                            throws EntityNotFoundException,
                                                                                                   DanglingReferenceException,
                                                                                                   DragosException

Returns a collection of entities referenced by this relation through relation ends.

In contrast to getRelationEndsOfRelation(RelationEndClass, boolean), this method does not return the relation ends themselves, but rather the related elements of each of these relation ends.

If type == null, this method will follow all relation ends belonging to this relation.

Parameters:

type - The type of the relation ends to follow (null means "any type").

includeSubClasses - Whether instances of subclasses of type should also be followed (has no effect if type == null).

set - If true, each entity is contained at most once in the returned collection, even if multiple relation ends lead to it.

Returns:

A collection of all relation ends.

Throws:

EntityNotFoundException - if type != null and type is not a dependent relation end class of relation's class.

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

DragosException - if anything went wrong.