ptolemy.actor.gt

Class GraphMatcher

java.lang.Object

ptolemy.actor.gt.GraphAnalyzer

ptolemy.actor.gt.GraphMatcher

public class GraphMatcher
extends GraphAnalyzer

Implementation of a recursive algorithm to match a pattern to any subgraph of a a graph. The pattern is specified as the pattern part of a graph transformation rule. The graph to be matched to, called host graph, is an arbitrary Ptolemy II model, whose top level is an instance of CompositeEntity.

Since:

Ptolemy II 7.1

Version:

$Id$

Author:

Thomas Huining Feng

Pt.AcceptedRating:

Red (tfeng)

Pt.ProposedRating:

Yellow (tfeng)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.actor.gt.GraphAnalyzer

GraphAnalyzer.IndexedList, GraphAnalyzer.IndexedLists, GraphAnalyzer.Path

Field Summary

Fields

Modifier and Type	Field and Description
static MatchCallback	DEFAULT_CALLBACK The default callback that always returns true.

Constructor Summary

Constructors

Constructor and Description
GraphMatcher()

Method Summary

Modifier and Type	Method and Description
protected boolean	_isIgnored(java.lang.Object object) Return whether the object in the pattern should be ignored in the pattern matching.
protected boolean	_isOpaque(CompositeEntity entity) Test whether the composite entity is opaque or not.
protected boolean	_relationCollapsing(NamedObj container) Return whether the interconnected relations should be collapsed into one in pattern matching.
MatchResult	getMatchResult() Return the most recent match result, which the user should not modify.
boolean	isSuccessful() Return whether the last matching was successful.
static void	main(java.lang.String[] args) Match a rule file to a model file.
boolean	match(Pattern pattern, CompositeEntity hostGraph) Match a pattern specified in the patternGraph to a model in hostGraph.
static GraphMatcher	match(java.lang.String ruleXMLFile, java.lang.String hostXMLFile) Match the rule stored in the file with name ruleXMLFile to the model stored in the file with name hostXMLFile, whose top-level should be an instance of CompositeEntity.
static GraphMatcher	match(java.lang.String ruleXMLFile, java.lang.String hostXMLFile, MatchCallback callback) Match the rule stored in the file with name ruleXMLFile to the model stored in the file with name hostXMLFile, whose top-level should be an instance of CompositeEntity, and invoke callback's MatchCallback.foundMatch(GraphMatcher) method whenever a match is found.
void	setMatchCallback(MatchCallback callback) Set the callback to be invoked by future calls to match(Pattern, CompositeEntity).

Methods inherited from class ptolemy.actor.gt.GraphAnalyzer

findFirstChild, findFirstPath, findNextChild, findNextPath

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CALLBACK

public static final MatchCallback DEFAULT_CALLBACK

The default callback that always returns true. A callback is invoked whenever a match is found. Because this callback always returns true, it terminates the matching process after the first match is found, and the match result can be obtained later using getMatchResult().

Constructor Detail

GraphMatcher

public GraphMatcher()

Method Detail

getMatchResult

public MatchResult getMatchResult()

Return the most recent match result, which the user should not modify. During the matching process, when a callback routine (an instance implementing MatchCallback) is invoked (see setMatchCallback(MatchCallback)), that callback routine can call this method to retrieve the match result that has just been found.

Note that the returned match result object may be changed by future matching. To maintain a copy, MatchResult.clone() may be called that returns a clone of it.

Returns:

The most recent match result.

isSuccessful

public boolean isSuccessful()

Return whether the last matching was successful.

Returns:

Whether the last matching was successful.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Match a rule file to a model file. This main method takes a parameter array of length 2 or 3. If the array's length is 2, the first string is the rule file name, and the second is the model file name. In this case, an arbitrary match (the first one found) is printed to the console. If the array has 3 elements, the first string should be "-A" (meaning "all matches"), the second string is the rule file name, and the third is the model file name. In that case, all the matches are printed to to console one by one.

Parameters:

args - The parameter array.

Throws:

java.lang.Exception - If the rule file or the model file cannot be read.

match

public boolean match(Pattern pattern,
                     CompositeEntity hostGraph)

Match a pattern specified in the patternGraph to a model in hostGraph. If the match is successful, true is returned, and the match result is stored internally, which can be retrieved with getMatchResult(). A matching was successful if at least one match result was found, and the callback (an instance implementing MatchCallback) returned true when it was invoked.

Parameters:

pattern - The pattern.

hostGraph - The host graph.

Returns:

true if the match is successful; false otherwise.

match

public static GraphMatcher match(java.lang.String ruleXMLFile,
                                 java.lang.String hostXMLFile)
                          throws java.lang.Exception

Match the rule stored in the file with name ruleXMLFile to the model stored in the file with name hostXMLFile, whose top-level should be an instance of CompositeEntity. The first match result (which is arbitrarily decided by the recursive algorithm) is recorded in the returned matcher object. This result can be obtained with getMatchResult(). If the match is unsuccessful, the match result is empty, and isSuccessful() of the returned matcher object returns false.

Parameters:

ruleXMLFile - The name of the file in which the rule is stored.

hostXMLFile - The name of the file in which the model to be matched is stored.

Returns:

A matcher object with the first match result stored in it. If no match is found, isSuccessful() of the matcher object returns false, and getMatchResult() returns an empty match.

Throws:

java.lang.Exception - If the rule file or the model file cannot be read.

See Also:

match(String, String, MatchCallback)

match

public static GraphMatcher match(java.lang.String ruleXMLFile,
                                 java.lang.String hostXMLFile,
                                 MatchCallback callback)
                          throws java.lang.Exception

Match the rule stored in the file with name ruleXMLFile to the model stored in the file with name hostXMLFile, whose top-level should be an instance of CompositeEntity, and invoke callback's MatchCallback.foundMatch(GraphMatcher) method whenever a match is found. If the callback returns true, the match will terminate and no more matches will be reported; otherwise, the match process continues, and the callback may be invoked again. If callback is null, the behavior is the same as match(String, String).

Parameters:

ruleXMLFile - The name of the file in which the rule is stored.

hostXMLFile - The name of the file in which the model to be matched is stored.

callback - The callback to be invoked when matches are found.

Returns:

A matcher object with the last match result stored in it. If no match is found, or though matches are found, the callback returns false for all the matches, then isSuccessful() of the matcher object returns false, and getMatchResult() returns an empty match.

Throws:

java.lang.Exception - If the rule file or the model file cannot be read.

See Also:

match(String, String)

setMatchCallback

public void setMatchCallback(MatchCallback callback)

Set the callback to be invoked by future calls to match(Pattern, CompositeEntity).

Parameters:

callback - The callback. If it is null, the callback is set to DEFAULT_CALLBACK.

See Also:

match(Pattern, CompositeEntity)

_isIgnored

protected boolean _isIgnored(java.lang.Object object)

Return whether the object in the pattern should be ignored in the pattern matching. An object is ignored if it is tagged to be ignored, or it is tagged to be optional but a match including that object has failed.

Overrides:

_isIgnored in class GraphAnalyzer

Parameters:

object - The object to be tested.

Returns:

true if the object is ignored.

_isOpaque

protected boolean _isOpaque(CompositeEntity entity)

Test whether the composite entity is opaque or not. Return true if the composite entity is an instance of CompositeActor and it is opaque. A composite actor is opaque if it has a director inside, which means the new level of hierarchy that it creates cannot be flattened, or it has a HierarchyFlatteningAttribute attribute inside with value true.

Specified by:

_isOpaque in class GraphAnalyzer

Parameters:

entity - The composite entity to be tested.

Returns:

true if the composite entity is an instance of CompositeActor and it is opaque.

_relationCollapsing

protected boolean _relationCollapsing(NamedObj container)

Return whether the interconnected relations should be collapsed into one in pattern matching.

Specified by:

_relationCollapsing in class GraphAnalyzer

Parameters:

container - The container of the relations.

Returns:

true if the relation should be collapsed.