notio
Class Relation

java.lang.Object
  |
  +--notio.Node
        |
        +--notio.Relation
All Implemented Interfaces:
java.io.Serializable
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. Relations with no arguments (zero valence) are allowed. Note that the terms 'arc' and 'argument' are used interchangably throughout the documentation.

Conceptually, the N arguments of a relation are all stored in one array, with zero being the index of the first argument. The first k elements of this array are considered to be inputs and the remaining N - k are outputs. This allows them to be both ordered and directed at the same time. The boundary between inputs and outputs is defined using the "output start index". This is the index into the array of arguments at which the first output argument occurs. If there are no outputs, the output start index is 1 greater than the number of inputs. Using setArguments() sets the entire array. Using setInputArgument() and setOutputArgument() sets the same array plus the index that defines where the outputs begin. That index can be set and found explicitly by calling setOutputStartIndex() and getOutputStartIndex(). In the end, it's all just one array and an index that shows where the outputs start. The default output start index for relations is N - 1, as specified by the standard.

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 occurrences of the specified argument with a new one regardless of whether it is an input or output argument.
 void replaceInputArgument(Concept oldConcept, Concept newConcept)
          Replaces all occurrences of the specified input argument with a new one.
 void replaceOutputArgument(Concept oldConcept, Concept newConcept)
          Replaces all occurrences of the specified output argument 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().
 void setType(RelationType newType)
          Sets the type for this relation.
 
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:
an array, possibly empty, containing 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:
an array, possibly empty, containing 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.

setType

public void setType(RelationType newType)
Sets the type for this relation. If a type has already been set, it will be replaced. If the new type has a valence that is different from the previous type and arguments have already been specified for this relation, the arguments will be updated as if isComplete() had been called.
Parameters:
newType - the new type for this relation.
See Also:
isComplete()

replaceArgument

public void replaceArgument(Concept oldConcept,
                            Concept newConcept)
Replaces all occurrences of the specified argument with a new one regardless of whether it is an input or output argument. Replacing nulls with non-nulls or vice-versa is allowed.
Parameters:
oldConcept - the concept being replaced.
newConcept - the replacement concept.

replaceInputArgument

public void replaceInputArgument(Concept oldConcept,
                                 Concept newConcept)
Replaces all occurrences of the specified input argument with a new one. Replacing nulls with non-nulls or vice-versa is allowed. Replacing an argument with null effectively removes that argument.
Parameters:
oldConcept - the input argument being replaced.
newConcept - the replacement argument.

replaceOutputArgument

public void replaceOutputArgument(Concept oldConcept,
                                  Concept newConcept)
Replaces all occurrences of the specified output argument with a new one. Replacing nulls with non-nulls or vice-versa is allowed. Replacing an argument with null effectively removes that argument.
Parameters:
oldConcept - the output argument being replaced.
newConcept - the replacement argument.

setArgument

public void setArgument(int index,
                        Concept newConcept)
Sets the specified argument to the specified concept. The index of the first argument (often labelled "1" in diagrams) is zero. 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. Setting an argument to null effectively removes that argument.
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. Setting an argument to null effectively removes that argument.
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. Setting an argument to null effectively removes that argument.
Parameters:
index - the index of the output argument being set (the nth output 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. If there are inputs, but no outputs, the output start index will be 1 greater than the number of inputs. This means that any code using the output start index to index into the array returned by getArguments() should check first to see if the array is long enough.
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 unless there are no outputs, in which case the index may be 1 greater than the length of the array. 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 includes null arguments. If this relation's type has a defined valence, the number returned by this method will equal the valence of the type.
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-2001 Finnegan Southey