Package ptolemy.actor.gt

Class 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)

    • 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)

      • _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.