notio
Class Relation

java.lang.Object
  |
  +--notio.Node
        |
        +--notio.Relation
Direct Known Subclasses:
Actor

public class Relation
extends Node
implements java.io.Serializable

The conceptual relation node class. This class encapsulates all available information about a conceptual relation within a graph. It consists of a type and/or arguments (concepts connected to the arcs of the relation). The arguments can be divided into input and output arguments as desired, though the default is that the last (and possibly only) argument is the sole output arc.

See Also:
Serialized Form

Constructor Summary
Relation()
          Constructs a new relation that has no type and no arguments.
Relation(Concept[] newArguments)
          Constructs a relation with no type and the specified arguments.
Relation(Concept[] newArguments, int newOutputStartIndex)
          Constructs a relation with no type and the specified arguments with output arguments starting at the specified index.
Relation(RelationType newType)
          Constructs a relation with the given type.
Relation(RelationType newType, Concept[] newArguments)
          Constructs a relation with the given type and arguments.
Relation(RelationType newType, Concept[] newInputArguments, Concept[] newOutputArguments)
          Constructs a relation with the given type and the specified input and output arguments.
Relation(RelationType newType, Concept[] newArguments, int newOutputStartIndex)
          Constructs a relation with the given type and arguments and output argument start index.
 
Method Summary
 Relation copy(CopyingScheme copyScheme)
          Performs a copy operation on this relation according to the the specified CopyingScheme.
 Relation copy(CopyingScheme copyScheme, java.util.Hashtable substitutionTable)
          Performs a copy operation on this relation according to the the specified CopyingScheme.
 Concept[] getArguments()
          Returns all of the concepts related by this relation.
 Concept[] getInputArguments()
          Returns the input arguments for this relation.
 Concept[] getOutputArguments()
          Returns the output arguments for this relation.
 int getOutputStartIndex()
          Returns the index of the first output argument within the array returned by getArguments().
 RelationType getType()
          Returns this relation's type.
 int getValence()
          This method returns the valence (number of arguments) that this relation has defined.
 boolean isComplete()
          Returns true if this relation's arguments are completely specified (are all non-null).
static boolean matchRelations(Relation first, Relation second, MatchingScheme matchingScheme)
          Compares two relations to decide if they match.
 boolean relatesConcept(Concept concept)
          Returns true if the specified concept is an argument of this relation.
 void replaceArgument(Concept oldConcept, Concept newConcept)
          Replaces all occurances of the specified argument with a new one regardless of whether it is an input or output arc.
 void replaceInputArgument(Concept oldConcept, Concept newConcept)
          Replaces all occurances of the specified input arc with a new one.
 void replaceOutputArc(Concept oldConcept, Concept newConcept)
          Replaces all occurances of the specified output arc with a new one.
 Relation restrictTo(RelationType subType)
          Returns a new node identical to this but restricted to the new type.
 void setArgument(int index, Concept newConcept)
          Sets the specified argument to the specified concept.
 void setArguments(Concept[] newConcepts)
          Sets the arguments according to the specified array of concepts.
 void setInputArgument(int index, Concept newConcept)
          Sets the specified argument to the specified concept.
 void setOutputArgument(int index, Concept newConcept)
          Sets the specified argument to the specified concept.
 void setOutputStartIndex(int newOutputStartIndex)
          Sets the index of the first output argument within the array returned by getArguments().
 
Methods inherited from class notio.Node
getComment, getEnclosingGraph, setComment
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Relation

public Relation(RelationType newType,
                Concept[] newArguments)
Constructs a relation with the given type and arguments. The last argument is assumed to be the sole output argument. The number of arguments must conform to the valence of the relation type unless it is unspecified in which case the valence is set to the number of arguments in the array.
Parameters:
newType - the type for this relation.
newArguments - the concepts related by this relation.

Relation

public Relation(RelationType newType,
                Concept[] newArguments,
                int newOutputStartIndex)
Constructs a relation with the given type and arguments and output argument start index. The number of arguments must conform to the valence of the relation type unless it is unspecified in which case the valence is set to the number of arguments in the array.
Parameters:
newType - the type for this relation.
newArguments - the concepts related by this relation.
newOutputStartIndex - the index into the newArguments array at which the output arcs start.

Relation

public Relation(RelationType newType,
                Concept[] newInputArguments,
                Concept[] newOutputArguments)
Constructs a relation with the given type and the specified input and output arguments. The number of arguments must conform to the valence of the relation type unless it is unspecified in which case the valence is set to the number of arguments in the array.
Parameters:
newType - the type for this relation.
newInputArguments - the input concepts related by this relation.
newOutputArguments - the output concepts related by this relation.

Relation

public Relation(RelationType newType)
Constructs a relation with the given type. The valence is taken from the specified type and the arguments are initialized to null. If the type's valence is unspecified, a zero-length argument array is used for construction. For a specified non-zero valence, the last argument is assumed to be the sole output argument.
Parameters:
newType - the type for this relation.

Relation

public Relation(Concept[] newArguments,
                int newOutputStartIndex)
Constructs a relation with no type and the specified arguments with output arguments starting at the specified index.
Parameters:
newArguments - the concepts related by this relation.
newOutputStartIndex - the index into the newArguments array at which the output arcs start.

Relation

public Relation(Concept[] newArguments)
Constructs a relation with no type and the specified arguments. For a non-zero valence, the last argument is assumed to be the sole output argument.
Parameters:
newArguments - the concepts related by this relation.

Relation

public Relation()
Constructs a new relation that has no type and no arguments. The number of arguments is automatically set to zero.
Method Detail

getType

public RelationType getType()
Returns this relation's type.
Returns:
this relation's type.

getArguments

public Concept[] getArguments()
Returns all of the concepts related by this relation. Input arguments are followed by output arguments. In a 'classic' relation, the last argument is always the sole output argument. If the relation has a type whose valence has changed since its definition, the arguments will not be adjusted. A call to isComplete() should be made to effect this adjustment.
Returns:
the arguments to this relation.

getInputArguments

public Concept[] getInputArguments()
Returns the input arguments for this relation. If the relation has a type whose valence has changed since its definition, the arguments will not be adjusted. A call to isComplete() should be made to effect this adjustment.
Returns:
the input arguments for this relation.

getOutputArguments

public Concept[] getOutputArguments()
Returns the output arguments for this relation. If the relation has a type whose valence has changed since its definition, the arguments will not be adjusted. A call to isComplete() should be made to effect this adjustment.
Returns:
the output arguments for this relation.

relatesConcept

public boolean relatesConcept(Concept concept)
Returns true if the specified concept is an argument of this relation.
Parameters:
concept - the concept being checked for.
Returns:
true if the specified concept is an argument of this relation.

replaceArgument

public void replaceArgument(Concept oldConcept,
                            Concept newConcept)
Replaces all occurances of the specified argument with a new one regardless of whether it is an input or output arc.
Parameters:
oldConcept - the concept being replaced.
newConcept - the replacement concept.

replaceInputArgument

public void replaceInputArgument(Concept oldConcept,
                                 Concept newConcept)
Replaces all occurances of the specified input arc with a new one.
Parameters:
oldConcept - the input arc being replaced.
newConcept - the replacement arc.

replaceOutputArc

public void replaceOutputArc(Concept oldConcept,
                             Concept newConcept)
Replaces all occurances of the specified output arc with a new one.
Parameters:
oldConcept - the output arc being replaced.
newConcept - the replacement arc.

setArgument

public void setArgument(int index,
                        Concept newConcept)
Sets the specified argument to the specified concept. If the argument has already been set, it will be replaced with the new value. If the valence of the relation type is defined and the specified index exceeds that valence, a IllegalArgumentException is thrown. If the valence is undefined and a previously unused argument index is specified, the valence of this particular relation will be increased to accomodate the index. No other relations nor the relation's type are affected by this increase. All currently specified arguments are preserved and any newly created but unspecified arguments are set to null. If the valence of the relation's type has changed since the arguments were specified, the arguments will be adjusted as if isComplete() had been called.
Parameters:
index - the index of the argument being set.
newConcept - the concept to be used as an argument.

setArguments

public void setArguments(Concept[] newConcepts)
Sets the arguments according to the specified array of concepts. If an argument has already been set, it will be replaced with the new value. If the valence of the relation type is defined and the number of arguments in the array exceeds that valence, a IllegalArgumentException is thrown. Otherwise, this method behaves like a series of calls to setArgument(), with the array index used as the argument's index.
Parameters:
newConcepts - the array of concepts to be used as arguments.
See Also:
setArgument(int, notio.Concept)

setInputArgument

public void setInputArgument(int index,
                             Concept newConcept)
Sets the specified argument to the specified concept. If the argument has already been set, it will be replaced with the new value. If the valence of the relation type is defined and the specified index exceeds that valence, a IllegalArgumentException is thrown. If the valence is undefined and a previously unused argument index is specified, the valence of this particular relation will be increased to accomodate the index. No other relations nor the relation's type are affected by this increase. All currently specified arguments are preserved and any newly created but unspecified arguments are set to null. If the valence of the relation's type has changed since the arguments were specified, the arguments will be adjusted as if isComplete() had been called.
Parameters:
index - the index of the input argument being set (the nth input argument).
newConcept - the concept to be used as an argument.

setOutputArgument

public void setOutputArgument(int index,
                              Concept newConcept)
Sets the specified argument to the specified concept. If the argument has already been set, it will be replaced with the new value. If the valence of the relation type is defined and the specified index exceeds that valence, a IllegalArgumentException is thrown. If the valence is undefined and a previously unused argument index is specified, the valence of this particular relation will be increased to accomodate the index. No other relations nor the relation's type are affected by this increase. All currently specified arguments are preserved and any newly created but unspecified arguments are set to null. If the valence of the relation's type has changed since the arguments were specified, the arguments will be adjusted as if isComplete() had been called.
Parameters:
index - the index of the output argument being set (the nth input argument).
newConcept - the concept to be used as an argument.

getOutputStartIndex

public int getOutputStartIndex()
Returns the index of the first output argument within the array returned by getArguments(). This method will return -1 if the relation has a valence of zero.
Returns:
the index of the first output argument within the array returned by getArguments().
See Also:
getArguments()

setOutputStartIndex

public void setOutputStartIndex(int newOutputStartIndex)
Sets the index of the first output argument within the array returned by getArguments(). For relations with a valence of zero, the only valid start index is -1. For all other valences, the start index must be within the array's range. Note that this method should rarely be needed since the start index can be specified in a constructor and it is unlikely to change. This method is provided chiefly for completeness.
Parameters:
newOutputStartIndex - the index of the first output argument within the array returned by getArguments().
See Also:
getArguments()

getValence

public int getValence()
This method returns the valence (number of arguments) that this relation has defined. This number include null references. If this relation's type has a defined valence, this number will equal that valence.
Returns:
the number of arguments this relation has defined (including nulls).

isComplete

public boolean isComplete()
Returns true if this relation's arguments are completely specified (are all non-null). If the relation has a type, its valence will be checked to ensure that the relation is complete according to the type. This check is made in case the valence of the type has changed. If it has changed, the arguments will be adjusted accordingly.
Returns:
true if this relation's arguments are all non-null.

copy

public Relation copy(CopyingScheme copyScheme)
Performs a copy operation on this relation according to the the specified CopyingScheme. The result may be a new node or simply a reference to this relation depending on the scheme.
Parameters:
copyScheme - the copying scheme used to control the copy operation.
Returns:
the result of the copy operation.

copy

public Relation copy(CopyingScheme copyScheme,
                     java.util.Hashtable substitutionTable)
Performs a copy operation on this relation according to the the specified CopyingScheme. The result may be a new node or simply a reference to this relation depending on the scheme.
Parameters:
copyScheme - the copying scheme used to control the copy operation.
substitutionTable - a hashtable containing copied objects available due to earlier copy operations.
Returns:
the result of the copy operation.

restrictTo

public Relation restrictTo(RelationType subType)
                    throws RestrictionException
Returns a new node identical to this but restricted to the new type.
Parameters:
subType - the type to be restricted to.
Returns:
the new restricted relation.
Throws:
RestrictionException - if subType is not a real subtype of the current type

matchRelations

public static boolean matchRelations(Relation first,
                                     Relation second,
                                     MatchingScheme matchingScheme)
Compares two relations to decide if they match. The exact semantics of matching are determined by the matching scheme.
Parameters:
first - the first relation being matched.
second - the second relation being matched.
matchingScheme - the matching scheme that determines how the match is performed.
Returns:
true if the two concepts match according to the scheme's criteria.


Copyright 1998-1999 Finnegan Southey