+ * The rule application result describes the result of applying a {@link TemporalRelationshipRule} + * on a task tree node. It contains a {@link RuleApplicationStatus} and a list of all parent + * task tree nodes that were created during a rule application. See the description of + * {@link TemporalRelationshipRule} for more details. + *
* - * @version $Revision: $ $Date: 18.03.2012$ - * @author 2012, last modified by $Author: patrick$ + * @author Patrick Harms */ -public class RuleApplicationResult { +class RuleApplicationResult { /** */ @@ -21,45 +25,45 @@ /** - * TODO: comment - * - * @param b + *+ * create a rule application result with a status {@link RuleApplicationStatus#RULE_NOT_APPLIED} + *
*/ - public RuleApplicationResult() { + RuleApplicationResult() { // this is the default indicating nothing so far } /** - * TODO: comment - * - * @param b + *+ * set the rule application status + *
*/ - public void setRuleApplicationStatus(RuleApplicationStatus status) { + void setRuleApplicationStatus(RuleApplicationStatus status) { this.status = status; } /** - * TODO: comment - * - * @return + *+ * return the rule application status + *
*/ - public RuleApplicationStatus getRuleApplicationStatus() { + RuleApplicationStatus getRuleApplicationStatus() { return status; } /** - * TODO: comment - * - * @param sequence + *+ * add a further parent node created during the rule application + *
*/ - public void addNewlyCreatedParentNode(ITaskTreeNode newParent) { + void addNewlyCreatedParentNode(ITaskTreeNode newParent) { newParents.add(newParent); } /** - * TODO: comment - * - * @return + *+ * return all parent nodes created during the rule application + *
*/ - public List+ * The rule application status describes the result of applying a {@link TemporalRelationshipRule} + * on a task tree node. See the description of {@link TemporalRelationshipRule} for more details. + *
* - * @version $Revision: $ $Date: 09.07.2012$ - * @author 2012, last modified by $Author: pharms$ + * @author Patrick Harms */ -public enum RuleApplicationStatus { +enum RuleApplicationStatus { RULE_APPLICATION_FINISHED, RULE_APPLICATION_FEASIBLE, Index: /trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRule.java =================================================================== --- /trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRule.java (revision 808) +++ /trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRule.java (revision 809) @@ -6,19 +6,50 @@ /** - * TODO comment + *+ * a temporal relation ship is able to detected temporal relationships between the child nodes + * of the parent node provided to the + * {@link #apply(ITaskTreeNode, ITaskTreeBuilder, ITaskTreeNodeFactory, boolean)} method. A rule + * created temporal relationships between the child nodes, i.e. substructures in the task tree, if + * it detects a temporal relationship and it can be sure that it is complete. Incomplete but + * detected temporal relationships may occur, if there can be more children expected to be added + * to the provided parent node. This could be the case during parsing a interaction log file of + * a GUI. + *
* - * @version $Revision: $ $Date: 12.02.2012$ - * @author 2012, last modified by $Author: patrick$ + * @author Patrick Harms */ -public interface TemporalRelationshipRule { +interface TemporalRelationshipRule { /** - * applies the rule to the given situation and returns a rule application result, if this was - * successful + *+ * applies the rule to the given parent node. The provided builder and node factory are used + * to create substructures in the task tree for the identified temporal relationships. The + * finalize parameter is used to command the rule to finish rule applications, in the case it + * is known that no further data will be available. + *
+ *+ * The returned rule application result is null, if the rule can not be applied, i.e. it does not + * detect a temporal relationship. It returns a rule application result with a status + * {@link RuleApplicationStatus#RULE_APPLICATION_FINISHED} if the rule was applied. The result + * contains all newly created parent nodes. It returns a rule application result with status + * {@link RuleApplicationStatus#RULE_APPLICATION_FEASIBLE} if the rule would be applicable if + * further children would be available in the parent node. This status MUST not be returned if + * the finalize parameter is true. In this case the rule must be applied or not. + *
+ * + * @param parent the parent node with the children to apply the rule on + * @param builder the builder to be used for creating substructures for the identified + * temporal relationships + * @param nodeFactory the node factory to be used for creating substructures for the identified + * temporal relationships + * @param finalize true, if the rule shall not expect further children to come and that it + * should therefore be applied in any case + * + * @return the rule application result as described. */ - public RuleApplicationResult apply(ITaskTreeNode parent, - ITaskTreeBuilder builder, - ITaskTreeNodeFactory nodeFactory, - boolean finalize); + RuleApplicationResult apply(ITaskTreeNode parent, + ITaskTreeBuilder builder, + ITaskTreeNodeFactory nodeFactory, + boolean finalize); } Index: /trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRuleManager.java =================================================================== --- /trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRuleManager.java (revision 808) +++ /trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRuleManager.java (revision 809) @@ -13,20 +13,78 @@ /** - * TODO comment + *+ * This class is responsible for applying temporal relationship rules on a task tree. Through this, + * a flat task tree is restructured to have more depth but to include more temporal relationships + * between task tree nodes which are not only a major sequence. I.e. through the application of + * rule iterations and selections of task tree nodes are detected. Which kind of temporal relations + * between task tree nodes are detected depends on the {@link TemporalRelationshipRule}s known to + * this class. + *
+ *The class holds references to the appropriate {@link TemporalRelationshipRule}s and calls + * their {@link TemporalRelationshipRule#apply(ITaskTreeNode, ITaskTreeBuilder, ITaskTreeNodeFactory, boolean)} + * method for each node in the task tree it is needed for. The general behavior of this class is + * the following: + *
+ * the node equality manager needed by the rules to compare task tree nodes with each other + *
+ */ private NodeEqualityRuleManager nodeEqualityRuleManager; - /** */ - private List+ * the temporal relationship rule known to the manager. The rules are applied in the order + * they occur in this list. + *
+ */ + private List+ * initialize the manager with a node equality rule manager to be used by the known rules + * for task tree node comparison. + *
*/ public TemporalRelationshipRuleManager(NodeEqualityRuleManager nodeEqualityRuleManager) { @@ -36,28 +94,38 @@ /** - * TODO: comment + *+ * initialized the temporal relationship rule manager by instantiating the known rules and + * providing them with a reference to the node equality manager or other information they need. + *
+ */ + public void init() { + rules.add(new DefaultGuiElementSequenceDetectionRule()); + rules.add(new DefaultEventTargetSequenceDetectionRule()); + rules.add(new TrackBarSelectionDetectionRule(nodeEqualityRuleManager)); + rules.add(new DefaultGuiEventSequenceDetectionRule()); + + rules.add(new DefaultIterationDetectionRule + (nodeEqualityRuleManager, NodeEquality.LEXICALLY_EQUAL)); + rules.add(new DefaultIterationDetectionRule + (nodeEqualityRuleManager, NodeEquality.SYNTACTICALLY_EQUAL)); + rules.add(new DefaultIterationDetectionRule + (nodeEqualityRuleManager, NodeEquality.SEMANTICALLY_EQUAL)); + } + + /** + *+ * applies the known rules to the provided parent node. For the creation of further nodes, + * the provided builder and node factory are utilized. If the finalize parameter is true, the + * rule application is finalized as far as possible without waiting for further data. If it is + * false, the rule application is broken up at the first rule returning, that its application + * would be feasible. + *
* - */ - public void init() { - ruleIndex.add(new DefaultGuiElementSequenceDetectionRule()); - ruleIndex.add(new DefaultEventTargetSequenceDetectionRule()); - ruleIndex.add(new TrackBarSelectionDetectionRule(nodeEqualityRuleManager)); - ruleIndex.add(new DefaultGuiEventSequenceDetectionRule()); - - ruleIndex.add(new DefaultIterationDetectionRule - (nodeEqualityRuleManager, NodeEquality.LEXICALLY_EQUAL)); - ruleIndex.add(new DefaultIterationDetectionRule - (nodeEqualityRuleManager, NodeEquality.SYNTACTICALLY_EQUAL)); - ruleIndex.add(new DefaultIterationDetectionRule - (nodeEqualityRuleManager, NodeEquality.SEMANTICALLY_EQUAL)); - } - - /** - * returns true, if there is a rule that matches the current situation and if, therefore, a new - * temporal relationship has been added to the tree. - * - * @param parent - * @param newChild - * @return + * @param parent the parent node to apply the rules on + * @param builder the task tree builder to be used for linking task tree nodes with each + * other + * @param nodeFactory the node factory to be used for instantiating new task tree nodes. + * @param finalize used to indicate, if the rule application shall break up if a rule would + * be feasible if further data was available, or not. */ public void applyRules(ITaskTreeNode parent, @@ -70,10 +138,21 @@ /** - * returns true, if there is a rule that matches the current situation and if, therefore, a new - * temporal relationship has been added to the tree. + *+ * applies the known rules to the provided parent node. For the creation of further nodes, + * the provided builder and node factory are utilized. If the finalize parameter is true, the + * rule application is finalized as far as possible without waiting for further data. If it is + * false, the rule application is broken up at the first rule returning, that its application + * would be feasible. The method calls itself for each parent node created through the rule + * application. In this case, the finalize parameter is always true. + *
* - * @param parent - * @param newChild - * @return + * @param parent the parent node to apply the rules on + * @param builder the task tree builder to be used for linking task tree nodes with each + * other + * @param nodeFactory the node factory to be used for instantiating new task tree nodes. + * @param finalize used to indicate, if the rule application shall break up if a rule would + * be feasible if further data was available, or not. + * @param logIndent simply used for loggin purposes to indent the log messages depending + * on the recursion depth of calling this method. */ private int applyRules(ITaskTreeNode parent, @@ -87,5 +166,5 @@ int noOfRuleApplications = 0; - for (TemporalRelationshipRule rule : ruleIndex) { + for (TemporalRelationshipRule rule : rules) { RuleApplicationResult result; do { @@ -130,6 +209,6 @@ /** - * - */ + * + */ /* * private void dumpTask(TaskTreeNode task, String indent) { System.err.print(indent);