i3.dragos.gm.core.proxy
Class GraphEntityClassProxy

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

All Implemented Interfaces:

ExistenceCheckable, GraphEntityClass, MetaAttributable

Direct Known Subclasses:

EdgeClassProxy, GraphClassProxy, NodeClassProxy, RelationClassProxy, RelationEndClassProxy

public class GraphEntityClassProxy
extends java.lang.Object
implements GraphEntityClass

A GraphEntityClassProxy delegates all method calls to the underlying graph entity class 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 GraphEntityClass

proxiedEntityClass The graph entity class we wrap.

Constructor Summary

GraphEntityClassProxy(GraphEntityClass proxiedEntityClass)
Constructs a new wrapper for a graph entity class.

Method Summary

void	addSubClass(GraphEntityClass clazz) Adds the specified class to the set of sub classes of this class.
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.
Attribute	declareAttribute(java.lang.String attrName, java.lang.Class type) Declares a new attribute with the given name and type.
boolean	equals(java.lang.Object o) Checks for equality with another object.
java.util.Collection<? extends Attribute>	getAllDeclaredAttributes() Returns a collection containg all attributes declared in this graph element class and all its super classes.
java.util.Map<java.lang.String,java.io.Serializable>	getAllMetaAttributes() Returns a map containing all currently set meta-attribute key-value pairs.
java.util.Collection<? extends GraphEntityClass>	getAllSubClasses() Returns all sub classes of this class.
java.util.Collection<? extends GraphEntityClass>	getAllSuperClasses() Returns all super classes of this class.
Attribute	getAttribute(java.lang.String attrName) Returns the attribute with the given name.
DataSourceURL	getDataSourceURL() Returns the URL to the data source that stores this graph entity class.
java.util.Collection<? extends Attribute>	getDeclaredAttributes() Returns a collection containing the attributes declared for the schema entity.
java.util.Collection<? extends GraphEntityClass>	getDirectSubClasses() Returns all direct sub classes of this class.
java.util.Collection<? extends GraphEntityClass>	getDirectSuperClasses() Returns all direct super classes of this class.
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.
java.lang.String	getName() Returns the name of the graph entity class.
GraphEntityClass	getProxyGraphEntityClass() Returns the graph entity class which is encapsulated by this proxy.
GraphEntityClass	getWrappedGraphEntityClass() Returns the wrapped entity class, null if none.
boolean	hasAttribute(java.lang.String attrName) Returns true if an attribute with the given name is declared in the graph entity class.
int	hashCode() To comply with the general contract for Object.hashCode(), it is recommended to return the hash code of the internal identifier.
boolean	isAbstract() Returns true if the schema entity is abstract or 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.
boolean	isSubClassOf(GraphEntityClass clazz) Returns true if the specified class is the same as this class or a super class of this class and false otherwise.
boolean	isSuperClassOf(GraphEntityClass clazz) Returns true if the specified class is the same as this class or a sub class of this class and false otherwise.
void	removeSubClass(GraphEntityClass clazz) Removes the specified class from the set of direct sub classes of this class.
void	setMetaAttribute(java.lang.String key, java.io.Serializable value) Sets a meta-attribute.
java.lang.String	toString()
void	undeclareAllAttributes() Undeclares all attributes of this graph entity class.
void	undeclareAttribute(Attribute attribute) Undeclares an attribute.
void	undeclareAttribute(java.lang.String attrName) Undeclares the attribute with the given name.
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

proxiedEntityClass

protected final GraphEntityClass proxiedEntityClass

The graph entity class we wrap.

Constructor Detail

GraphEntityClassProxy

public GraphEntityClassProxy(GraphEntityClass proxiedEntityClass)

Constructs a new wrapper for a graph entity class.

Parameters:

proxiedEntityClass - The entity class to be wrapped.

Method Detail

getProxyGraphEntityClass

public GraphEntityClass getProxyGraphEntityClass()

Returns the graph entity class which is encapsulated by this proxy.

Returns:

graph entity class which is encapsulated by this proxy.

getDataSourceURL

public DataSourceURL getDataSourceURL()

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

Specified by:

getDataSourceURL in interface GraphEntityClass

Returns:

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

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 Schema.getGraphEntityClassByInternalIdentifier(Serializable) As alternative you may consider to use the classes in the package i3.dragos.gm.core.schema.id.

Specified by:

getInternalIdentifier in interface GraphEntityClass

Returns:

the internal identifier.

getName

public java.lang.String getName()
                         throws DragosException

Returns the name of the graph entity class.

Specified by:

getName in interface GraphEntityClass

Returns:

the name of the graph entity class.

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 GraphEntityClass

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 GraphEntityClass

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.

declareAttribute

public Attribute declareAttribute(java.lang.String attrName,
                                  java.lang.Class type)
                           throws EntityAlreadyExistsException,
                                  DragosException

Declares a new attribute with the given name and type. Neither name nor type are allowed to be null.

Specified by:

declareAttribute in interface GraphEntityClass

Parameters:

attrName - The name of the attribute.

type - The type of the attribute.

Returns:

the new attribute.

Throws:

EntityAlreadyExistsException - if an attribute with the given name already exists.

DragosException - if something went wrong.

undeclareAttribute

public void undeclareAttribute(java.lang.String attrName)
                        throws EntityNotFoundException,
                               DragosException

Undeclares the attribute with the given name.

All instances of this attribute are removed from the graph pool associated with this schema, using GraphPool.removeAllAttributeInstances(Attribute), before the attribute itself is undeclared.

Note that this method only works for attributes declared for this class, not for those declared for any super classes in the inheritance hierachy.

Specified by:

undeclareAttribute in interface GraphEntityClass

Parameters:

attrName - The name of the attribute.

Throws:

EntityNotFoundException - if no attribute with the given name is declared for this GraphEntityClass.

DragosException - if something went wrong.

undeclareAttribute

public void undeclareAttribute(Attribute attribute)
                        throws EntityNotFoundException,
                               DragosException

Undeclares an attribute.

All instances of this attribute are removed from the graph pool associated with this schema, using GraphPool.removeAllAttributeInstances(Attribute), before the attribute itself is undeclared.

Note that this method only works for attributes declared for this class, not for those declared for any super classes in the inheritance hierachy.

Specified by:

undeclareAttribute in interface GraphEntityClass

Parameters:

attribute - The attribute.

Throws:

EntityNotFoundException - if the attribute is not declared for this GraphEntityClass.

DragosException - if something went wrong.

undeclareAllAttributes

public void undeclareAllAttributes()
                            throws DragosException

Undeclares all attributes of this graph entity class.

All instances of an attribute are removed from the graph pool associated with this schema, using GraphPool.removeAllAttributeInstances(Attribute), before the attribute itself is undeclared. You may first remove all instances of all attributes, and then undeclare all attributes at once, or you may process each attribute seperately at your discretion.

Note that this method only works for attributes declared for this class, not for those declared for any super classes in the inheritance hierachy.

Specified by:

undeclareAllAttributes in interface GraphEntityClass

Throws:

DragosException - if something went wrong.

getDeclaredAttributes

public java.util.Collection<? extends Attribute> getDeclaredAttributes()
                                                                throws DragosException

Returns a collection containing the attributes declared for the schema entity. The elements in the collection are of type Attribute.

Note that this method only works for attributes declared for this class, not for those declared for any super classes in the inheritance hierachy.

Specified by:

getDeclaredAttributes in interface GraphEntityClass

Returns:

A Collection containing the attributes declared for the graph entity class.

Throws:

DragosException - if something went wrong.

getAttribute

public Attribute getAttribute(java.lang.String attrName)
                       throws EntityNotFoundException,
                              DragosException

Returns the attribute with the given name.

Note that this method only works for attributes declared for this class, not for those declared for any super classes in the inheritance hierachy.

Specified by:

getAttribute in interface GraphEntityClass

Parameters:

attrName - The name of the requested attribute.

Returns:

the attrinbute with the given name.

Throws:

EntityNotFoundException - if no attribute with the given name exists.

DragosException - if something went wrong.

hasAttribute

public boolean hasAttribute(java.lang.String attrName)
                     throws DragosException

Returns true if an attribute with the given name is declared in the graph entity class.

Note that this method only works for attributes declared for this class, not for those declared for any super classes in the inheritance hierachy.

Specified by:

hasAttribute in interface GraphEntityClass

Parameters:

attrName - The name of the requested attribute.

Returns:

the attrinbute with the given name.

Throws:

DragosException - if something went wrong.

addSubClass

public void addSubClass(GraphEntityClass clazz)
                 throws EntityNotFoundException,
                        DragosException

Adds the specified class to the set of sub classes of this class.

If clazz is already a direct sub class of this class, no action will be performed. Of course, this class will be added to the list of super classes of clazz.

If adding this sub class would result in circular references, a InheritanceCycleException is thrown, and no action will be performed.

When called on a specialized subinterface of GraphEntityClass (e.g. EdgeClass), the argument must be of the same type. You can not subclass an EdgeClass with a RelationClass, for example. If the parameter is invalid, a DragosException is thrown, and no action will be performed.

Specified by:

addSubClass in interface GraphEntityClass

Parameters:

clazz - The class which should be a sub class of this class.

Throws:

EntityNotFoundException - if clazz does not exist in this schema.

InheritanceCycleException - if the inheritance relation would introduce a cycle.

DragosException - if clazz is of a different specialized type, or an internal error occurs.

removeSubClass

public void removeSubClass(GraphEntityClass clazz)
                    throws EntityNotFoundException,
                           DragosException

Removes the specified class from the set of direct sub classes of this class. Of course, this class will also be removed from the list of super classes of clazz.

Specified by:

removeSubClass in interface GraphEntityClass

Parameters:

clazz - The sub class to remove.

Throws:

EntityNotFoundException - if clazz does not exist in this schema or is not a direct sub class.

DragosException - in case of internal errors.

getDirectSuperClasses

public java.util.Collection<? extends GraphEntityClass> getDirectSuperClasses()
                                                                       throws DragosException

Returns all direct super classes of this class. The elements in the collection are of type GraphEntityClass.

Specified by:

getDirectSuperClasses in interface GraphEntityClass

Returns:

all direct super classes of this class.

Throws:

DragosException - if something went wrong.

getAllSuperClasses

public java.util.Collection<? extends GraphEntityClass> getAllSuperClasses()
                                                                    throws DragosException

Returns all super classes of this class. The elements in the collection are of type GraphEntityClass.

While the sub class relationship is reflective (meaning c.isSuperClassOf(c) returns true for any GraphEntityClass c), the class this method is called on itself will not be included in the returned Collection. This decision was made because in practical use of this method one in most cases is only interested in real super classes.

Specified by:

getAllSuperClasses in interface GraphEntityClass

Returns:

all super classes of this class.

Throws:

DragosException - if something went wrong.

getDirectSubClasses

public java.util.Collection<? extends GraphEntityClass> getDirectSubClasses()
                                                                     throws DragosException

Returns all direct sub classes of this class. The elements in the collection are of type GraphEntityClass.

Specified by:

getDirectSubClasses in interface GraphEntityClass

Returns:

all direct sub classes of this class.

Throws:

DragosException - if something went wrong.

getAllSubClasses

public java.util.Collection<? extends GraphEntityClass> getAllSubClasses()
                                                                  throws DragosException

Returns all sub classes of this class. The elements in the collection are of type GraphEntityClass.

While the sub class relationship is reflective (meaning c.isSubClassOf(c) returns true for any GraphEntityClass c), the class this method is called on itself will not be included in the returned Collection. This decision was made because in practical use of this method one in most cases is only interested in real sub classes.

Specified by:

getAllSubClasses in interface GraphEntityClass

Returns:

all sub classes of this class.

Throws:

DragosException - if something went wrong.

isSuperClassOf

public boolean isSuperClassOf(GraphEntityClass clazz)
                       throws EntityNotFoundException,
                              DragosException

Returns true if the specified class is the same as this class or a sub class of this class and false otherwise.

Specified by:

isSuperClassOf in interface GraphEntityClass

Parameters:

clazz - The class which is tested.

Returns:

true if the specified class is a super class of this class and false otherwise.

Throws:

EntityNotFoundException - if the graph element class could not be found.

DragosException - if something went wrong.

isSubClassOf

public boolean isSubClassOf(GraphEntityClass clazz)
                     throws EntityNotFoundException,
                            DragosException

Returns true if the specified class is the same as this class or a super class of this class and false otherwise.

Specified by:

isSubClassOf in interface GraphEntityClass

Parameters:

clazz - The class which is tested.

Returns:

true if the specified class is a super class of this class and false otherwise.

Throws:

EntityNotFoundException - if the graph element class could not be found.

DragosException - if something went wrong.

isAbstract

public boolean isAbstract()
                   throws DragosException

Returns true if the schema entity is abstract or false otherwise. If a graph element class is abstract no graph element can be constructed for it.

Specified by:

isAbstract in interface GraphEntityClass

Returns:

true if the schema entity is abstract or false otherwise.

Throws:

DragosException - if something went wrong.

getAllDeclaredAttributes

public java.util.Collection<? extends Attribute> getAllDeclaredAttributes()
                                                                   throws DragosException

Returns a collection containg all attributes declared in this graph element class and all its super classes. The elements in the collection are of type Attribute.

Specified by:

getAllDeclaredAttributes in interface GraphEntityClass

Returns:

collection containg all attributes declared in this graph element class.

Throws:

DragosException - if something went wrong.

getWrappedGraphEntityClass

public GraphEntityClass getWrappedGraphEntityClass()

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

Specified by:

getWrappedGraphEntityClass in interface GraphEntityClass

Returns:

the wrapped entity class, 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.