jcreek.representation
Class Relation

java.lang.Object
  extended byjcreek.representation.Relation
All Implemented Interfaces:
java.lang.Cloneable

public class Relation
extends java.lang.Object
implements java.lang.Cloneable

The Relation class represents a relation (like an edge in a graph) between two entities. Associated with each relation is a RelationType object that siginifies its type. If the RelationType has an inverse type, an inverse relation is also created (in the other direction) between the two entities.

Version:
1.1
Author:
Frode Sørmo

Constructor Summary
protected Relation(Entity from, Entity type, Entity value, double strength, boolean ignore)
          Creates a new relation without supplying a RelationType object (the RelationType class is really a convinience class of a representation level higher than Relation since the type of a relation in the formalism is represented by an Entity).
  Relation(Entity from, RelationType type, Entity value)
          Create a new relation of a given type from an origin entity to a target entity.
  Relation(Entity from, RelationType type, Entity value, double strength)
          Create a new relation of a given type from an origin entity to a target entity.
  Relation(Entity from, RelationType type, Entity value, Relation override)
          Create a new relation of a given type from an origin entity to a target entity.
 
Method Summary
 void addOriginal(Relation rel)
          If this relation is inherited, this method adds a relation that is counted as beeing among the originals of this relations.
protected  void addOverriddenBy(Relation rel)
           
 void addOverriding(Relation override)
          This relation is market as overriding another relation.
 java.lang.Object clone()
          Returns a clone of this relation.
 void confirm()
          If this relation is temporary (e.g. inherited), this method will make it permanent and decouple it from its original source.
 boolean equals(java.lang.Object ob)
          Two entities are considered equal if they represent the same RelationData object.
 long getCreationTime()
          Returns the time of creation of this relation, in the the format as System.currentTimeMillis();
 Partition getCurrentPartition()
          Returns the current partition, if set.
 java.lang.String getDescription()
          Returns a description of this relation.
 ExplanationModel getExplanationModel()
          If this relation is inherited, this method returns the model that justifies the inheritance.
 Explanation[] getExplanations()
          Returns an array of explanations for this relation.
 double getExplanationStrength()
          Returns the strength variable contains the explanation strength for this relation.
 Entity getFrom()
          Returns the entity from where the relation originates.
 java.lang.Object getID()
          Returns the unique ID of this relation.
 Relation getInverse()
          Returns the reverse of this relation, i.e. the relation going from the target of this relation to the origin of this relation with a relation type that is the inverse of this relation's type.
 java.lang.String getInverseName()
          getInverseName returns the name of the inverse relation.
 KnowledgeModel getKnowledgeModel()
          Returns the knowledgemodel this relation belongs to.
 java.lang.String getName()
          Returns the name of this relation.
 java.lang.String getNaturalInverseName()
          Returns the natural inverse name of the relation.
 java.lang.String getNaturalName()
          Returns the natural name of the relation.
 Relation[] getOriginal()
          When this relation is an inherited relation, it returnes the original relation it was inherited from.
 Relation[] getOverridenBy()
          Returns which relations this relation is overriden by.
 Relation[] getOverridingRelations()
          Returns the relations (if any) this relation overrides.
 SubModel getPathModel()
          If this relation is inherited, this method returns a submodel of the knowledgemodel which contains all relations and all entities contained in all explanation-paths from the origin to the target entity.
protected  RelationData getRelationData()
          Returns this relation's RelationData object.
 RelationType getRelationType()
          Returns an instance of RelationType describing this relations type.
 Entity getValue()
          Returns the entity this relation is pointing at.
 int hashCode()
          Overrides the hashCode() method to match the class' new equals() method.
 boolean hasInverse()
          Returns true if this relation has an inverse relation.
 boolean hasOriginal(Relation rel)
          Returns true if the supplied relations is among the originals of this relation.
 Relation inherit(Entity inheritedTo, ExplanationModel model)
          When inheriting a relation, a copy of the relation is made and returned.
 boolean isInherited()
          Returns true if this relation is inherited.
 boolean isNegated()
          Returns true if this relation is negated, i.e. represents an explicit representation of a lack of relation between two entities.
 boolean isOverridden()
          Returns true if there is at least one relation overriding this relation.
 boolean isOverriding()
          Returns true if this relation overrides another relation.See setOverriding().
 boolean isPersistent()
          Returns true if this relation is composite, i.e. composed of a chain of relations.
static void main(java.lang.String[] argv)
           
 void negate()
          Sets the explanation strength to 0 - in effect representing explicitly that there is NOT a relationship of this kind between the two entities.
 void remove()
          Removes this relation.
protected  void removeOverriddenBy(Relation rel)
           
 void removeOverriding(Relation override)
          Removes a relation from the list of overridden relations.
 void setDescription(java.lang.String description)
          Sets the description of this relation.
 void setExplanationStrength(double value)
          Sets the strength variable contains the explanation strength for this relation.
 void setFrom(Entity from)
          Sets the from-entity (the origin) of the relation.
 void setRelationType(RelationType relationType)
          Sets the relation-type of this relation.
 void setValue(Entity value)
          Sets the value (the target) of the relation.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Relation

protected Relation(Entity from,
                   Entity type,
                   Entity value,
                   double strength,
                   boolean ignore)
Creates a new relation without supplying a RelationType object (the RelationType class is really a convinience class of a representation level higher than Relation since the type of a relation in the formalism is represented by an Entity). This should only be used to define the very core of the model i.e. the relation used to define a relation type.


Relation

public Relation(Entity from,
                RelationType type,
                Entity value)
Create a new relation of a given type from an origin entity to a target entity. This automatically also creates a relation in the opposite direction (from the target entity to the origin entity) of the opposite type.

Parameters:
type - The type of the relation to create.
from - The origin entity - where the relation is from.
value - The target entity - where the relation is pointing to.

Relation

public Relation(Entity from,
                RelationType type,
                Entity value,
                double strength)
Create a new relation of a given type from an origin entity to a target entity. This automatically also creates a relation in the opposite direction (from the target entity to the origin entity) of the opposite type.

Parameters:
type - The type of the relation to create.
from - The origin entity - where the relation is from.
value - The target entity - where the relation is pointing to.
strength - The explanation strength of the relation.

Relation

public Relation(Entity from,
                RelationType type,
                Entity value,
                Relation override)
Create a new relation of a given type from an origin entity to a target entity. This automatically also creates a relation in the opposite direction (from the target entity to the origin entity) of the opposite type. In addition, this relation is market as overriding another relation. This means that if both relations are found to be (either directly or through inheritance) present in an entity, this relation will supress the other relation so it will not be returned.

Parameters:
type - The type of the relation to create.
from - The origin entity - where the relation is from.
value - The target entity - where the relation is pointing to.
override - The relation that this relation overrides.
Method Detail

remove

public void remove()
Removes this relation. This will also automatically remove the inverse of this relation.


setExplanationStrength

public void setExplanationStrength(double value)
Sets the strength variable contains the explanation strength for this relation. This value must be [0.0..1.0] - any value below this range is set to 0.0, any value above this range is set to 1.0. If this realtion is temporary (e.g. inherited), this will confirm the relation and set the local explanation strength - it will not change the explanation strength of the original relation this relation is derrived from (e.g. inherited from). See the confirm() method.

Parameters:
value - The explanation strength.

getExplanationStrength

public double getExplanationStrength()
Returns the strength variable contains the explanation strength for this relation. If not set, the default for the class is used. If the task is too complex to calculate, 0.0 will be returned.


negate

public void negate()
Sets the explanation strength to 0 - in effect representing explicitly that there is NOT a relationship of this kind between the two entities. Useful for exceptions to general rules (i.e. all birds flies, except penguins etc.) If this realtion is temporary (e.g. inherited), this will confirm the relation and set the local explanation strength - it will not change the explanation strength of the original relation this relation is derrived from (e.g. inherited from). See the confirm() method.


isNegated

public boolean isNegated()
Returns true if this relation is negated, i.e. represents an explicit representation of a lack of relation between two entities.


getValue

public Entity getValue()
Returns the entity this relation is pointing at.


getFrom

public Entity getFrom()
Returns the entity from where the relation originates.


getInverseName

public java.lang.String getInverseName()
getInverseName returns the name of the inverse relation.


getName

public java.lang.String getName()
Returns the name of this relation.


hasInverse

public boolean hasInverse()
Returns true if this relation has an inverse relation. Normally all relations have that.


getNaturalInverseName

public java.lang.String getNaturalInverseName()
Returns the natural inverse name of the relation. By "natural", is ment a form that can be used to generate natural language sentences. For a relation, this is usually a verb phrase.


getNaturalName

public java.lang.String getNaturalName()
Returns the natural name of the relation. By "natural", is ment a form that can be used to generate natural language sentences. For a relation, this is usually a verb phrase.


getInverse

public Relation getInverse()
Returns the reverse of this relation, i.e. the relation going from the target of this relation to the origin of this relation with a relation type that is the inverse of this relation's type.


getRelationType

public RelationType getRelationType()
Returns an instance of RelationType describing this relations type.


addOverriding

public void addOverriding(Relation override)
This relation is market as overriding another relation. This means that if both relations are found to be (either directly or through inheritance) present in an entity, this relation will supress the other relation so it will not be returned.


removeOverriding

public void removeOverriding(Relation override)
Removes a relation from the list of overridden relations.


getOverridingRelations

public Relation[] getOverridingRelations()
Returns the relations (if any) this relation overrides. See addOverriding().


isOverriding

public boolean isOverriding()
Returns true if this relation overrides another relation.See setOverriding().


isOverridden

public boolean isOverridden()
Returns true if there is at least one relation overriding this relation. See setOverriding().


getOverridenBy

public Relation[] getOverridenBy()
Returns which relations this relation is overriden by. See setOverriding().


removeOverriddenBy

protected void removeOverriddenBy(Relation rel)

addOverriddenBy

protected void addOverriddenBy(Relation rel)

setValue

public void setValue(Entity value)
Sets the value (the target) of the relation. This also updates the inverse relation.

Parameters:
value - The new value of the relation.

setFrom

public void setFrom(Entity from)
Sets the from-entity (the origin) of the relation. This also updates the inverse relation.

Parameters:
from - The new from-entity of the relation.

setRelationType

public void setRelationType(RelationType relationType)
Sets the relation-type of this relation. This also changes the relation-type of the inverse relation.

Parameters:
relationType - The new relation-type.

equals

public boolean equals(java.lang.Object ob)
Two entities are considered equal if they represent the same RelationData object.


hashCode

public int hashCode()
Overrides the hashCode() method to match the class' new equals() method.


getDescription

public java.lang.String getDescription()
Returns a description of this relation.


setDescription

public void setDescription(java.lang.String description)
Sets the description of this relation.


getKnowledgeModel

public KnowledgeModel getKnowledgeModel()
Returns the knowledgemodel this relation belongs to.


getCreationTime

public long getCreationTime()
Returns the time of creation of this relation, in the the format as System.currentTimeMillis();


inherit

public Relation inherit(Entity inheritedTo,
                        ExplanationModel model)
When inheriting a relation, a copy of the relation is made and returned. This means that the original origin entity is changed to the entity this relation is inherited to.

Parameters:
inheritedTo - The entity this relation shall be inherited to.
model - The ExplanationModel justifying this inheritance.

getExplanationModel

public ExplanationModel getExplanationModel()
If this relation is inherited, this method returns the model that justifies the inheritance. If it is not inherited, null is returned.


getPathModel

public SubModel getPathModel()
If this relation is inherited, this method returns a submodel of the knowledgemodel which contains all relations and all entities contained in all explanation-paths from the origin to the target entity.


getExplanations

public Explanation[] getExplanations()
                              throws TaskTooComplexException
Returns an array of explanations for this relation. This is only valid if this relation is composite, i.e. not a single relation. This task is NP-hard and as such it may throw a TaskTooComplexException if the task is above a treshold which currently is a constant.

Throws:
TaskTooComplexException

isInherited

public boolean isInherited()
Returns true if this relation is inherited.


isPersistent

public boolean isPersistent()
Returns true if this relation is composite, i.e. composed of a chain of relations.


getOriginal

public Relation[] getOriginal()
When this relation is an inherited relation, it returnes the original relation it was inherited from.


hasOriginal

public boolean hasOriginal(Relation rel)
Returns true if the supplied relations is among the originals of this relation. This is only relevant for inherited relations, and as such this method will always return false for non-inherited relations.

Parameters:
rel - The relation to test.

addOriginal

public void addOriginal(Relation rel)
If this relation is inherited, this method adds a relation that is counted as beeing among the originals of this relations. This method is usually only used by an InheritanceMethod.

Parameters:
rel - The (additional) original relation.

confirm

public void confirm()
If this relation is temporary (e.g. inherited), this method will make it permanent and decouple it from its original source.


getRelationData

protected RelationData getRelationData()
Returns this relation's RelationData object.


getCurrentPartition

public Partition getCurrentPartition()
Returns the current partition, if set.


getID

public java.lang.Object getID()
Returns the unique ID of this relation. The kind of object this method returns depends on the implementation of the RelationData method.


clone

public java.lang.Object clone()
Returns a clone of this relation.


toString

public java.lang.String toString()

main

public static void main(java.lang.String[] argv)


Created at IDI, NTNU by the Artificial Intelligence and Learning group