i3.dragos.gm.core.proxy
Class GraphEntityProxy

java.lang.Object
  i3.dragos.gm.core.proxy.GraphEntityProxy

All Implemented Interfaces:

GraphEntity, ExistenceCheckable, MetaAttributable

Direct Known Subclasses:

EdgeProxy, GraphProxy, NodeProxy, RelationEndProxy, RelationProxy

public class GraphEntityProxy
extends java.lang.Object
implements GraphEntity

A GraphEntityProxy delegates all method calls to the underlying graph entity except for those that access fields which are used after a graph entity has been deleted. The fields are:

• Data source URL
• Internal Identifier

For details on background see: ProxyWrapper.

Author:

Boris Boehlen <boehlen@cs.rwth-aachen.de>

Field Summary

protected GraphEntity

proxiedEntity The graph entity we wrap.

Constructor Summary

GraphEntityProxy(GraphEntity proxiedEntity)
Constructs a new wrapper for a graph entity.

Method Summary

void	checkExistence() Checks whether this object still exists, throwing an exception if not.
void	checkExistenceOptional() Checks whether this object still exists, throwing an exception if not.
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<java.lang.String,java.io.Serializable>	getAllMetaAttributes() Returns a map containing all currently set meta-attribute key-value pairs.
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.
java.io.Serializable	getMetaAttribute(java.lang.String key) Returns the current value of a meta-attribute.
Graph	getParent() Returns the graph this graph element is contained in.
GraphEntity	getProxyGraphEntity() Returns the graph entity which is encapsulated by this proxy.
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.
boolean	isMetaAttributeKeyReserved(java.lang.String key) Checks whether a meta-attribute key is reserved for internal use.
boolean	isMetaAttributeSet(java.lang.String key) Checks whether a meta-attribute is set.
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.
void	setMetaAttribute(java.lang.String key, java.io.Serializable value) Sets a meta-attribute.
java.lang.String	toString()
void	unsetMetaAttribute(java.lang.String key) Removes a meta-attribute.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

proxiedEntity

protected final GraphEntity proxiedEntity

The graph entity we wrap.

Constructor Detail

GraphEntityProxy

public GraphEntityProxy(GraphEntity proxiedEntity)

Constructs a new wrapper for a graph entity.

Parameters:

proxiedEntity - The entity to be wrapped.

Method Detail

getProxyGraphEntity

public GraphEntity getProxyGraphEntity()

Returns the graph entity which is encapsulated by this proxy.

Returns:

graph entity which is encapsulated by this proxy.

getDataSourceURL

public DataSourceURL getDataSourceURL()

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

Specified by:

getDataSourceURL in interface GraphEntity

Returns:

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

getInternalIdentifier

public 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.

Specified by:

getInternalIdentifier in interface GraphEntity

Returns:

the internal identifier.

getGraphEntityClass

public GraphEntityClass getGraphEntityClass()
                                     throws DragosException

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

Specified by:

getGraphEntityClass in interface GraphEntity

Returns:

The graph entity's type.

Throws:

DragosException - if something went wrong.

equals

public 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.

Specified by:

equals in interface GraphEntity

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

public int hashCode()

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

Specified by:

hashCode in interface GraphEntity

Overrides:

hashCode in class java.lang.Object

Returns:

The hash code.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

checkExistence

public void checkExistence()
                    throws java.lang.RuntimeException

Checks whether this object still exists, throwing an exception if not. This method should be called by all writing operations.

Specified by:

checkExistence in interface ExistenceCheckable

Throws:

java.lang.RuntimeException - if this object no longer exists or an error occurred while accessing the GraphPool.

checkExistenceOptional

public void checkExistenceOptional()
                            throws java.lang.RuntimeException

Checks whether this object still exists, throwing an exception if not. This method should be called by all reading operations.

A useful default implementation would be as follows:

 try {
     GraphPool gp = GraphPoolFactory.get(getDataSourceURL());
     if (gp.getForceExistenceCheckOnRead()) {
         checkExistence();
     }
 } catch (DragosException e) {
     String message = "Caught GraphPoolException while trying to determine whether to perform checks on read operation!";
     log.error(message);
     throw new RuntimeException(message);
 }
 

Specified by:

checkExistenceOptional in interface ExistenceCheckable

Throws:

java.lang.RuntimeException - if this object no longer exists or an error occurred while accessing the GraphPool.

getParent

public Graph getParent()
                throws DragosException

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

Specified by:

getParent in interface GraphEntity

Returns:

the graph this graph element is contained in.

Throws:

DragosException

putAttributeValue

public 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.

Specified by:

putAttributeValue in interface GraphEntity

Parameters:

attribute - The attribute.

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

Throws:

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

DragosException - if something went wrong.

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

getAttributeValue

public 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.

Specified by:

getAttributeValue in interface GraphEntity

Parameters:

attribute - The attribute that should be retrieved.

Returns:

The value of the attribute.

Throws:

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

public 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}.

Specified by:

getAllValidAttributeValues in interface GraphEntity

Returns:

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

Throws:

DragosException - if something went wrong.

setAttributeInvalid

public 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.

Specified by:

setAttributeInvalid in interface GraphEntity

Parameters:

attribute - The attribute.

Throws:

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

DragosException - if something went wrong.

isAttributeValid

public 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.

Specified by:

isAttributeValid in interface GraphEntity

Parameters:

attribute - The attribute.

Returns:

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

Throws:

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

DragosException - if something went wrong.

getEdges

public 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.

Specified by:

getEdges in interface GraphEntity

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

public 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.

Specified by:

getEdges in interface GraphEntity

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

public boolean isIncident(Edge edge)
                   throws DragosException

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

Specified by:

isIncident in interface GraphEntity

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

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

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

Specified by:

getAdjacentGraphEntities in interface GraphEntity

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

public 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().

Specified by:

getRelationEnds in interface GraphEntity

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

public 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().

Specified by:

getRelationEnds in interface GraphEntity

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

public 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().

Specified by:

getRelationEnds in interface GraphEntity

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

public boolean isIncident(RelationEnd relationEnd)
                   throws DragosException

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

Specified by:

isIncident in interface GraphEntity

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

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

Returns all adjacent Relations connected through RelationEnds.

As with GraphEntity.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.

Specified by:

getAdjacentRelations in interface GraphEntity

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

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

Returns all adjacent Relations connected through RelationEnds.

As with GraphEntity.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.

Specified by:

getAdjacentRelations in interface GraphEntity

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

public 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.

Specified by:

getWrappedGraphEntity in interface GraphEntity

Returns:

the wrapped entity, null if none.

setMetaAttribute

public void setMetaAttribute(java.lang.String key,
                             java.io.Serializable value)
                      throws EntityInUseException,
                             DragosException

Sets a meta-attribute. Any old value will be overwritten.

Specified by:

setMetaAttribute in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

value - The (new) value of this meta-attribute.

Throws:

EntityInUseException - if a key name is reserved for internal use.

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

unsetMetaAttribute

public void unsetMetaAttribute(java.lang.String key)
                        throws EntityInUseException,
                               DragosException

Removes a meta-attribute. If no value was set before, this method has no effect.

Specified by:

unsetMetaAttribute in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

Throws:

EntityInUseException - if a key name is reserved for internal use.

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

getMetaAttribute

public java.io.Serializable getMetaAttribute(java.lang.String key)
                                      throws EntityNotFoundException,
                                             DragosException

Returns the current value of a meta-attribute.

Specified by:

getMetaAttribute in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

Returns:

The current value of this meta-attribute.

Throws:

EntityNotFoundException - if no meta-attribute with that name exists.

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

isMetaAttributeSet

public boolean isMetaAttributeSet(java.lang.String key)
                           throws EntityNotFoundException,
                                  DragosException

Checks whether a meta-attribute is set. Meta-attributes with reserved keys are not treated in any special way by this method.

Specified by:

isMetaAttributeSet in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

Returns:

true if the meta-attribute is set, false otherwise.

Throws:

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

EntityNotFoundException

getAllMetaAttributes

public java.util.Map<java.lang.String,java.io.Serializable> getAllMetaAttributes()
                                                                          throws DragosException

Returns a map containing all currently set meta-attribute key-value pairs.

Specified by:

getAllMetaAttributes in interface MetaAttributable

Returns:

A Map containing key-value pairs for all set meta-attributes.

Throws:

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

isMetaAttributeKeyReserved

public boolean isMetaAttributeKeyReserved(java.lang.String key)
                                   throws DragosException

Checks whether a meta-attribute key is reserved for internal use.

Specified by:

isMetaAttributeKeyReserved in interface MetaAttributable

Parameters:

key - The key in question.

Returns:

true if this meta-attribute key is reserved, false otherwise.

Throws:

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.