notio
Class Graph

java.lang.Object
  |
  +--notio.Graph

public class Graph
extends java.lang.Object
implements java.io.Serializable

The basic conceptual graph class.

See Also:
Serialized Form

Constructor Summary
Graph()
          Constructs an empty graph.
 
Method Summary
 void addComment(java.lang.String newComment)
          Adds a comment to this graph.
 void addConcept(Concept newConcept)
          Adds a concept to this graph.
 void addConcepts(Concept[] newConcepts)
          Adds one or more concepts to this graph.
 void addRelation(Relation newRelation)
          Adds a relation to this graph and adds any related concepts that are not already in this graph at the same time.
 void addRelations(Relation[] newRelations)
          Adds one or more relations to this graph and adds any related concepts that are not already in this graph at the same time.
 Graph copy(CopyingScheme copyScheme)
          Performs a copy operation on this graph according to the the specified CopyingScheme.
 Graph copy(CopyingScheme copyScheme, java.util.Hashtable substitutionTable)
          Performs a copy operation on this graph according to the the specified CopyingScheme.
 void expandConceptType(Concept concept)
          Performs minimal type expansion on the specified concept if a type definition is available for that type.
 void expandConceptType(Concept[] concepts)
          Performs minimal type expansion on the specified concepts if type definitions is available for their types.
 void expandConceptType(ConceptType conceptType)
          Performs minimal type expansion on all concepts in this graph of the specified type, if a type definition is available for that type.
 void expandRelationType(Relation relation)
          Performs minimal type expansion on the specified relation if a type definition is available for that type.
 void expandRelationType(Relation[] relations)
          Performs minimal type expansion on the specified relations if type definitions is available for their types.
 void expandRelationType(RelationType relationType)
          Performs minimal type expansion on all relations in this graph of the specified type, if a type definition is available for that type.
 Actor[] getActorRelations()
          Returns a list of the those relations in this graph that are actors.
 boolean getAllowIncompleteRelations()
          Returns the flag setting for this graph indicating whether or not incomplete relations and actors may be added to this graph.
 java.lang.String[] getComments()
          Returns an array of all comments associated with this graph.
 Concept[] getConcepts()
          Returns a list of the concepts in this graph.
 Concept[] getConceptsWithExactType(ConceptType conType)
          Returns all concepts in the graph with exactly the type specified.
 Concept[] getConceptsWithSubType(ConceptType conType)
          Returns all concepts in the graph that are supertypes of the specified type (which includes the type itself).
 Concept[] getConceptsWithSuperType(ConceptType conType)
          Returns all concepts in the graph that are subtypes of the specified type (which includes the type itself).
 Concept getContext()
          Returns the context of this graph or null if this graph is in the outermost context.
 int getContextDepth()
          Returns the context depth (level of nesting) of this graph.
 Graph getContextGraph()
          Returns the graph containing the context of this graph or null if this graph is not enclosed by a graph.
 Referent getEnclosingReferent()
          Return the enclosing referent for this graph if it is nested or null otherwise.
static Concept[] getMatchingConcepts(Graph first, Graph second, MatchingScheme matchingScheme)
          For each concept the first graph, this method finds what concepts match it from the second graph.
static Relation[] getMatchingRelations(Graph first, Graph second, MatchingScheme matchingScheme)
          For each relation the first graph, this method finds what relations match it from the second graph.
 Relation[] getNormalRelations()
          Returns a list of the those relations in this graph that are NOT actors.
 int getNumberOfConcepts()
          Returns the number of concepts in this graph.
 int getNumberOfRelations()
          Returns the number of relations in this graph.
 Relation[] getRelations()
          Returns a list of the relations in this graph.
 Relation[] getRelationsWithExactType(RelationType relType)
          Returns all relations in the graph with exactly the type specified.
 Relation[] getRelationsWithSubType(RelationType relType)
          Returns all relations in the graph that are supertypes of the specified type (which includes the type itself).
 Relation[] getRelationsWithSuperType(RelationType relType)
          Returns all relations in the graph that are subtypes of the specified type (which includes the type itself).
 boolean hasConcept(Concept concept)
          Returns true if the graph contains the specified concept.
 boolean hasConcepts(Concept[] conceptArr)
          Returns true if the graph contains the specified concepts.
 boolean hasRelation(Relation relation)
          Returns true if the graph contains the specified relation.
 boolean hasRelations(Relation[] relationArr)
          Returns true if the graph reltains the specified relations.
 boolean isBlank()
          Returns true if this graph is blank.
 boolean isComplete()
          Returns true if this graph is complete.
 boolean isEnclosedBy(Concept concept)
          Returns true if this graph is enclosed by the specified concept.
 boolean isEnclosedBy(Graph graph)
          Returns true if this graph is enclosed by the specified graph.
static Graph join(Graph firstGraph, Concept[] firstConcepts, Graph secondGraph, Concept[] secondConcepts, MatchingScheme matchingScheme, CopyingScheme copyScheme)
          Joins two graphs on the specified concept nodes using the specified matching scheme to determine if the nodes form a valid join point.
static Graph join(Graph firstGraph, Concept firstConcept, Graph secondGraph, Concept secondConcept, MatchingScheme matchingScheme, CopyingScheme copyScheme)
          Joins two graphs on the specified concept nodes using the specified matching scheme to determine if the nodes form a valid join point.
static MatchResult matchGraphs(Graph first, Graph second, MatchingScheme matchingScheme)
          Attempts to matches between the two specified graphs and returns the results in a MatchResult object.
static Graph[] maximalJoin(Graph firstGraph, Graph secondGraph, MatchingScheme matchingScheme, CopyingScheme copyScheme)
          Maximally joins two graphs using all possible mappings.
static Graph[] maximalJoin(Graph firstGraph, Graph secondGraph, MatchingScheme matchingScheme, CopyingScheme copyScheme, int N)
          Maximally joins two graphs, using N or fewer node mappings, depending on what is possible.
 void removeComment(java.lang.String deadComment)
          Removes a comment from this graph.
 void removeConcept(Concept deadConcept)
          Removes the specified concept from this graph.
 void removeConcepts(Concept[] deadConcepts)
          Removes the specified concepts from this graph.
 void removeRelation(Relation deadRelation)
          Removes the specified relation from this graph.
 void removeRelations(Relation[] deadRelations)
          Removes the specified relations from this graph.
 void replaceConcept(Concept oldConcept, Concept newConcept)
          Replaces one concept with another in a graph.
 void setAllowIncompleteRelations(boolean flag)
          Sets a flag for this graph indicating whether or not incomplete relations and actors may be added to this graph.
 void simplify()
          Simplifies all relations in this graph.
 void simplify(Relation relation)
          Simplifies the specified relation node by removing any duplicates of that relation in this graph.
 void simplify(RelationType relType)
          Simplifies all instances of the specified relation type in this graph.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Graph

public Graph()
Constructs an empty graph.
Method Detail

addConcept

public void addConcept(Concept newConcept)
                throws ConceptAddError
Adds a concept to this graph. If the concept is already part of the graph, nothing is changed and no exception is thrown.
Parameters:
newConcept - the concept to be added.
Throws:
ConceptAddError - if the specified concept is already part of another graph.

addConcepts

public void addConcepts(Concept[] newConcepts)
                 throws ConceptAddError
Adds one or more concepts to this graph. Any nulls in the array of concepts will be ignored.
Parameters:
newConcepts - the array of concepts to be added.
Throws:
ConceptAddError - if one of the concepts is already part of another graph. All concepts before the offending concept are still added.

addRelation

public void addRelation(Relation newRelation)
                 throws RelationAddError,
                        ConceptAddError
Adds a relation to this graph and adds any related concepts that are not already in this graph at the same time.
Parameters:
newRelation - the relation to be added.
Throws:
RelationAddError - if newRelation already belongs to another graph, or if newRelation is incomplete and this graph does not allow incomplete relations.
ConceptAddError - if an error is thrown whilst adding one of arguments.
See Also:
getAllowIncompleteRelations()

addRelations

public void addRelations(Relation[] newRelations)
                  throws RelationAddError,
                         ConceptAddError
Adds one or more relations to this graph and adds any related concepts that are not already in this graph at the same time. Any nulls in the array of relations will be ignored.
Parameters:
newRelations - the array of relations to be added.
Throws:
RelationAddError - if one of the relations already belongs to another graph. All additions up to the one that causes the error are still performed.
ConceptAddError - if an error is thrown whilst adding one of arguments.

replaceConcept

public void replaceConcept(Concept oldConcept,
                           Concept newConcept)
                    throws ConceptReplaceException
Replaces one concept with another in a graph. The new concept fills exactly the same role as the old concept with respect to relations and coreference sets.
Parameters:
oldConcept - the old concept being replaced.
newConcept - the new concept that replaces the old.
Throws:
ConceptReplaceException - if oldConcept is not present in the graph.

removeConcept

public void removeConcept(Concept deadConcept)
                   throws ConceptRemoveException
Removes the specified concept from this graph. Any relations involving the concept must be removed before the concept may be removed. Any corefence links to this concept are also removed.
Parameters:
deadConcept - the concept to be removed.
Throws:
ConceptRemoveException - if deadConcept is involved in a relation in this graph, or if deadConcept is not present in this graph, or if removal of deadConcept will result in an invalid coreference set.

removeConcepts

public void removeConcepts(Concept[] deadConcepts)
                    throws ConceptRemoveException
Removes the specified concepts from this graph. Any nulls in the array will be ignored.
Parameters:
deadConcepts - the array of concepts to be removed.
Throws:
ConceptRemoveException - if one of the concepts is part of a relation in this graph, or if one of the concepts is not present in this graph, or if one of the removals will result in an invalid coreference set. All removals up to the one that causes the exception are still performed.

removeRelation

public void removeRelation(Relation deadRelation)
Removes the specified relation from this graph. If the relation is not part of this graph, nothing happens. Note: This does not remove any of the related concepts.
Parameters:
deadRelation - the relation to be removed.

removeRelations

public void removeRelations(Relation[] deadRelations)
Removes the specified relations from this graph. If a relation is not part of the graph, nothing happens and all other relations are removed as usual. Any nulls in the array will be ignored. Note: This does not remove any of the related concepts.
Parameters:
deadRelations - the array of relations to be removed.

getContext

public Concept getContext()
Returns the context of this graph or null if this graph is in the outermost context. This may also be thought of as the enclosing concept of this graph, accessible via the enclosing referent. This method is provided for convenience since the enclosing concept of a graph is often of interest.
Returns:
the concept that is the context of the graph or null if it is not enclosed by a concept.

getContextGraph

public Graph getContextGraph()
Returns the graph containing the context of this graph or null if this graph is not enclosed by a graph. This is equivalent to calling getEnclosingGraph() in this graph's context (if it has one). This method is provided for convenience since the enclosing graph of a graph is often of interest.
Returns:
the concept that is the context of the graph or null if it is not enclosed by a graph.

getEnclosingReferent

public Referent getEnclosingReferent()
Return the enclosing referent for this graph if it is nested or null otherwise.
Returns:
returns the referent enclosing this graph or null if it is not enclosed by by a referent.

getContextDepth

public int getContextDepth()
Returns the context depth (level of nesting) of this graph. A depth of zero indicates that this graph is at the outermost level.
Returns:
the context depth of this graph.

isEnclosedBy

public boolean isEnclosedBy(Concept concept)
Returns true if this graph is enclosed by the specified concept.
Parameters:
concept - the concept being checked for as enclosing this graph.
Returns:
true if this graph is enclosed by the specified concept.

isEnclosedBy

public boolean isEnclosedBy(Graph graph)
Returns true if this graph is enclosed by the specified graph.
Parameters:
graph - the graph being checked for as enclosing this graph.
Returns:
true if this graph is enclosed by the specified graph.

getConcepts

public Concept[] getConcepts()
Returns a list of the concepts in this graph. No guarantee is made as to the ordering of the concepts in the array. Subsequent calls to this method may produce different orderings.
Returns:
an array containing all concepts in this graph.

getNumberOfConcepts

public int getNumberOfConcepts()
Returns the number of concepts in this graph.
Returns:
the number of concepts in this graph.

getRelations

public Relation[] getRelations()
Returns a list of the relations in this graph. This includes all relations that Actors rather than just Relations. No guarantee is made as to the ordering of the relations in the array. Subsequent calls to this method may produce different orderings.
Returns:
an array containing all relations in this graph.

getNumberOfRelations

public int getNumberOfRelations()
Returns the number of relations in this graph. This includes all relations including Actors rather than just Relations.
Returns:
the number of relations in this graph.

getActorRelations

public Actor[] getActorRelations()
Returns a list of the those relations in this graph that are actors. No guarantee is made as to the ordering of the actors in the array. Subsequent calls to this method may produce different orderings.
Returns:
an array containing all actors in this graph.

getNormalRelations

public Relation[] getNormalRelations()
Returns a list of the those relations in this graph that are NOT actors. No guarantee is made as to the ordering of the relations in the array. Subsequent calls to this method may produce different orderings.
Returns:
an array containing all non-actor relations in this graph.

hasConcept

public boolean hasConcept(Concept concept)
Returns true if the graph contains the specified concept.
Parameters:
concept - the concept being checked for.
Returns:
true if the specified concept is part of this graph.

hasConcepts

public boolean hasConcepts(Concept[] conceptArr)
Returns true if the graph contains the specified concepts.
Parameters:
conceptArr - the array of concepts being checked for.
Returns:
true if the specified concepts are part of this graph.

hasRelation

public boolean hasRelation(Relation relation)
Returns true if the graph contains the specified relation.
Parameters:
relation - the relation being checked for.
Returns:
true if the specified relation is part of this graph.

hasRelations

public boolean hasRelations(Relation[] relationArr)
Returns true if the graph reltains the specified relations.
Parameters:
relationArr - the array of relations being checked for.
Returns:
true if the specified relations are part of this graph.

getConceptsWithExactType

public Concept[] getConceptsWithExactType(ConceptType conType)
Returns all concepts in the graph with exactly the type specified. Subtypes will not be included.
Parameters:
conType - the concept type to be matched exactly.
Returns:
an array of all concepts of the exactly the specified type or null if no concepts of the specified type are present in the graph.

getConceptsWithSuperType

public Concept[] getConceptsWithSuperType(ConceptType conType)
Returns all concepts in the graph that are subtypes of the specified type (which includes the type itself).
Parameters:
conType - the concept type whose subtypes will be matched.
Returns:
an array of all concepts that are subtypes of the specified type.

getConceptsWithSubType

public Concept[] getConceptsWithSubType(ConceptType conType)
Returns all concepts in the graph that are supertypes of the specified type (which includes the type itself).
Parameters:
conType - the concept type whose supertypes will be matched.
Returns:
an array of all concepts that are supertypes of the specified type.

getRelationsWithExactType

public Relation[] getRelationsWithExactType(RelationType relType)
Returns all relations in the graph with exactly the type specified. Subtypes will not be included.
Parameters:
relType - the relation type to be matched exactly.
Returns:
an array of all relations of the exactly the specified type or null if no relations of the specified type are present in the graph.

getRelationsWithSuperType

public Relation[] getRelationsWithSuperType(RelationType relType)
Returns all relations in the graph that are subtypes of the specified type (which includes the type itself).
Parameters:
relType - the relation type whose subtypes will be matched.
Returns:
an array of all relations that are subtypes of the specified type.

getRelationsWithSubType

public Relation[] getRelationsWithSubType(RelationType relType)
Returns all relations in the graph that are supertypes of the specified type (which includes the type itself).
Parameters:
relType - the relation type whose supertypes will be matched.
Returns:
an array of all relations that are supertypes of the specified type.

expandConceptType

public void expandConceptType(Concept concept)
                       throws TypeExpansionException
Performs minimal type expansion on the specified concept if a type definition is available for that type.
Parameters:
concept - the concept which is to undergo type expansion.

expandConceptType

public void expandConceptType(Concept[] concepts)
                       throws TypeExpansionException
Performs minimal type expansion on the specified concepts if type definitions is available for their types.
Parameters:
concepts - the array of concepts to undergo type expansion.

expandConceptType

public void expandConceptType(ConceptType conceptType)
                       throws TypeExpansionException
Performs minimal type expansion on all concepts in this graph of the specified type, if a type definition is available for that type.
Parameters:
conceptType - the concept type to expand.

expandRelationType

public void expandRelationType(Relation relation)
                        throws TypeExpansionException
Performs minimal type expansion on the specified relation if a type definition is available for that type.
Parameters:
relation - the relation which is to undergo type expansion.

expandRelationType

public void expandRelationType(Relation[] relations)
                        throws TypeExpansionException
Performs minimal type expansion on the specified relations if type definitions is available for their types.
Parameters:
relations - the array of relations to undergo type expansion.

expandRelationType

public void expandRelationType(RelationType relationType)
                        throws TypeExpansionException
Performs minimal type expansion on all relations in this graph of the specified type, if a type definition is available for that type.
Parameters:
relationType - the relation type to expand.

isBlank

public boolean isBlank()
Returns true if this graph is blank. Blank means that there are no concepts, relations, or actors in this graph.
Returns:
true if this graph is blank.

isComplete

public boolean isComplete()
Returns true if this graph is complete. A complete graph is one in which all relations are complete.
Returns:
true if this graph is complete.
See Also:
Relation.isComplete()

copy

public Graph copy(CopyingScheme copyScheme)
Performs a copy operation on this graph according to the the specified CopyingScheme. This method will always produce a new Graph object and only nested graphs will be affect by the value of MatchingScheme.getGraphFlag().
Parameters:
copyScheme - the copying scheme used to control the copy operation.
Returns:
the result of the copy operation.

copy

public Graph copy(CopyingScheme copyScheme,
                  java.util.Hashtable substitutionTable)
Performs a copy operation on this graph according to the the specified CopyingScheme. This method will always produce a new object of the exact same type as the original and only nested graphs will be affected by the value of MatchingScheme.getGraphFlag(). Note that the flag returned by Graph.getAllowIncompleteRelation() will be copied to the new graph.
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.
See Also:
getAllowIncompleteRelations()

join

public static Graph join(Graph firstGraph,
                         Concept firstConcept,
                         Graph secondGraph,
                         Concept secondConcept,
                         MatchingScheme matchingScheme,
                         CopyingScheme copyScheme)
                  throws JoinException
Joins two graphs on the specified concept nodes using the specified matching scheme to determine if the nodes form a valid join point.
Parameters:
firstGraph - the first graph to be joined.
firstConcept - the joining concept in the first graph.
secondGraph - the second graph to be joined.
secondConcept - the joining concept in the second graph.
matchingScheme - the matching scheme used to determine if the specified concepts are a valid join point.
copyScheme - the copying scheme used to create the new graph from the two being joined.
Returns:
the graph that results from the join.
Throws:
JoinException - if specified concepts are not part of the specified graphs and/or if the concepts do not form a valid join point.

join

public static Graph join(Graph firstGraph,
                         Concept[] firstConcepts,
                         Graph secondGraph,
                         Concept[] secondConcepts,
                         MatchingScheme matchingScheme,
                         CopyingScheme copyScheme)
                  throws JoinException
Joins two graphs on the specified concept nodes using the specified matching scheme to determine if the nodes form a valid join point.
Parameters:
firstGraph - the first graph to be joined.
firstConcepts - the joining concepts in the first graph.
secondGraph - the second graph to be joined.
secondConcepts - the joining concepts in the second graph.
matchingScheme - the matching scheme used to determine if the specified concepts form valid join points.
copyScheme - the copying scheme used to create the new graph from the two being joined.
Returns:
the graph that results from the join.
Throws:
JoinException - if specified concepts are not part of the specified graphs and/or if the concepts do not form valid join points.

maximalJoin

public static Graph[] maximalJoin(Graph firstGraph,
                                  Graph secondGraph,
                                  MatchingScheme matchingScheme,
                                  CopyingScheme copyScheme)
                           throws JoinException
Maximally joins two graphs using all possible mappings.
Parameters:
firstGraph - the first graph to be joined.
secondGraph - the second graph to be joined.
matchingScheme - the matching scheme used to determine if the specified concepts form valid join points.
copyScheme - the copying scheme used to create the new graph from the two being joined.
Returns:
the graphs that form the set of all possible maximal joins or null if no join exists.
Throws:
JoinException - if specified concepts are not part of the specified graphs and/or if the concepts do not form valid join points.

maximalJoin

public static Graph[] maximalJoin(Graph firstGraph,
                                  Graph secondGraph,
                                  MatchingScheme matchingScheme,
                                  CopyingScheme copyScheme,
                                  int N)
                           throws JoinException
Maximally joins two graphs, using N or fewer node mappings, depending on what is possible. If the specified N less than 1, all possible mappings will be used.
Parameters:
firstGraph - the first graph to be joined.
secondGraph - the second graph to be joined.
matchingScheme - the matching scheme used to determine if the specified concepts form valid join points.
copyScheme - the copying scheme used to create the new graph from the two being joined.
N - the maximum number of graphs that will be produced.
Returns:
up to N graphs that are maximal joins or null if no join exists.
Throws:
JoinException - if specified concepts are not part of the specified graphs and/or if the concepts do not form valid join points.

simplify

public void simplify(Relation relation)
Simplifies the specified relation node by removing any duplicates of that relation in this graph.
Parameters:
relation - the relation node to simplify.
Throws:
java.lang.IllegalArgumentException - if the specified relation is not part of this graph.

simplify

public void simplify(RelationType relType)
Simplifies all instances of the specified relation type in this graph.
Parameters:
relType - the relation type whose instances are to be simplified.

simplify

public void simplify()
Simplifies all relations in this graph.

matchGraphs

public static MatchResult matchGraphs(Graph first,
                                      Graph second,
                                      MatchingScheme matchingScheme)
Attempts to matches between the two specified graphs and returns the results in a MatchResult object. Matching is governed by the specified MatchingScheme.
Parameters:
first - the first graph being matched.
second - the second graph being matched.
matchingScheme - the matching scheme that determines how the match is performed.
Returns:
the MatchResult object describing the details of the match.

getMatchingConcepts

public static Concept[] getMatchingConcepts(Graph first,
                                            Graph second,
                                            MatchingScheme matchingScheme)
For each concept the first graph, this method finds what concepts match it from the second graph. Returns an array of concepts from the second graph that match the first graph's concepts.
Parameters:
first - the first graph from which concepts are to be matched.
second - the second graph from which concepts are to be matched.
matchingScheme - the matching scheme that determines how the match is performed.
Returns:
an array of matching concepts from the second graph.

getMatchingRelations

public static Relation[] getMatchingRelations(Graph first,
                                              Graph second,
                                              MatchingScheme matchingScheme)
For each relation the first graph, this method finds what relations match it from the second graph. Returns an array of relations from the second graph that match the first graph's relations.
Parameters:
first - the first graph from which relations are to be matched.
second - the second graph from which relations are to be matched.
matchingScheme - the matching scheme that determines how the match is performed.
Returns:
an array of matching relations from the second graph.

addComment

public void addComment(java.lang.String newComment)
Adds a comment to this graph. The comment has no strict interpretation but may be used be applications or humans to discover extra information about this graph.
Parameters:
newComment - the comment to be added to this graph.

removeComment

public void removeComment(java.lang.String deadComment)
Removes a comment from this graph. Removes the first occurrence of the specified comment from this graph. If the comment is not part of this graph, nothing happens.
Parameters:
deadComment - the comment to be removed from this graph.

getComments

public java.lang.String[] getComments()
Returns an array of all comments associated with this graph.
Returns:
an array of Strings (possibly empty) that are all the comments associated with this graph.

setAllowIncompleteRelations

public void setAllowIncompleteRelations(boolean flag)
Sets a flag for this graph indicating whether or not incomplete relations and actors may be added to this graph. An incomplete relation (or actor) is one which returns false when its isComplete() method is called. Note that changing this flag from true to false does not guarantee that all relations/actors in the graph are complete. The check is only performed when the node is added. Use the Graph.isComplete() method to check whether a graph is complete.
Parameters:
flag - the new setting for this flag.
See Also:
Relation.isComplete(), Relation.isComplete(), isComplete()

getAllowIncompleteRelations

public boolean getAllowIncompleteRelations()
Returns the flag setting for this graph indicating whether or not incomplete relations and actors may be added to this graph.
Returns:
the flag setting for this graph.


Copyright 1998-1999 Finnegan Southey