Changeset 809


Ignore:
Timestamp:
09/12/12 10:57:15 (12 years ago)
Author:
pharms
Message:
  • added some java doc for the classes, which are expected to be quite final
Location:
trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/RuleApplicationResult.java

    r655 r809  
    77 
    88/** 
    9  * TODO comment 
     9 * <p> 
     10 * The rule application result describes the result of applying a {@link TemporalRelationshipRule} 
     11 * on a task tree node. It contains a {@link RuleApplicationStatus} and a list of all parent 
     12 * task tree nodes that were created during a rule application. See the description of 
     13 * {@link TemporalRelationshipRule} for more details. 
     14 * </p> 
    1015 *  
    11  * @version $Revision: $ $Date: 18.03.2012$ 
    12  * @author 2012, last modified by $Author: patrick$ 
     16 * @author Patrick Harms 
    1317 */ 
    14 public class RuleApplicationResult { 
     18class RuleApplicationResult { 
    1519 
    1620    /** */ 
    … …  
    2125 
    2226    /** 
    23      * TODO: comment 
    24      *  
    25      * @param b 
     27     * <p> 
     28     * create a rule application result with a status {@link RuleApplicationStatus#RULE_NOT_APPLIED} 
     29     * </p> 
    2630     */ 
    27     public RuleApplicationResult() { 
     31    RuleApplicationResult() { 
    2832        // this is the default indicating nothing so far 
    2933    } 
    3034 
    3135    /** 
    32      * TODO: comment 
    33      *  
    34      * @param b 
     36     * <p> 
     37     * set the rule application status 
     38     * </p> 
    3539     */ 
    36     public void setRuleApplicationStatus(RuleApplicationStatus status) { 
     40    void setRuleApplicationStatus(RuleApplicationStatus status) { 
    3741        this.status = status; 
    3842    } 
    3943 
    4044    /** 
    41      * TODO: comment 
    42      *  
    43      * @return 
     45     * <p> 
     46     * return the rule application status 
     47     * </p> 
    4448     */ 
    45     public RuleApplicationStatus getRuleApplicationStatus() { 
     49    RuleApplicationStatus getRuleApplicationStatus() { 
    4650        return status; 
    4751    } 
    4852 
    4953    /** 
    50      * TODO: comment 
    51      *  
    52      * @param sequence 
     54     * <p> 
     55     * add a further parent node created during the rule application 
     56     * </p> 
    5357     */ 
    54     public void addNewlyCreatedParentNode(ITaskTreeNode newParent) { 
     58    void addNewlyCreatedParentNode(ITaskTreeNode newParent) { 
    5559        newParents.add(newParent); 
    5660    } 
    5761 
    5862    /** 
    59      * TODO: comment 
    60      *  
    61      * @return 
     63     * <p> 
     64     * return all parent nodes created during the rule application 
     65     * </p> 
    6266     */ 
    63     public List<ITaskTreeNode> getNewlyCreatedParentNodes() { 
     67    List<ITaskTreeNode> getNewlyCreatedParentNodes() { 
    6468        return newParents; 
    6569    } 

  • trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/RuleApplicationStatus.java

    r655 r809  
    22 
    33/** 
    4  * TODO comment 
     4 * <p> 
     5 * The rule application status describes the result of applying a {@link TemporalRelationshipRule} 
     6 * on a task tree node. See the description of {@link TemporalRelationshipRule} for more details. 
     7 * </p> 
    58 *  
    6  * @version $Revision: $ $Date: 09.07.2012$ 
    7  * @author 2012, last modified by $Author: pharms$ 
     9 * @author Patrick Harms 
    810 */ 
    9 public enum RuleApplicationStatus { 
     11enum RuleApplicationStatus { 
    1012    RULE_APPLICATION_FINISHED, 
    1113    RULE_APPLICATION_FEASIBLE, 

  • trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRule.java

    r655 r809  
    66 
    77/** 
    8  * TODO comment 
     8 * <p> 
     9 * a temporal relation ship is able to detected temporal relationships between the child nodes 
     10 * of the parent node provided to the 
     11 * {@link #apply(ITaskTreeNode, ITaskTreeBuilder, ITaskTreeNodeFactory, boolean)} method. A rule 
     12 * created temporal relationships between the child nodes, i.e. substructures in the task tree, if 
     13 * it detects a temporal relationship and it can be sure that it is complete. Incomplete but 
     14 * detected temporal relationships may occur, if there can be more children expected to be added 
     15 * to the provided parent node. This could be the case during parsing a interaction log file of 
     16 * a GUI. 
     17 * </p> 
    918 *  
    10  * @version $Revision: $ $Date: 12.02.2012$ 
    11  * @author 2012, last modified by $Author: patrick$ 
     19 * @author Patrick Harms 
    1220 */ 
    13 public interface TemporalRelationshipRule { 
     21interface TemporalRelationshipRule { 
    1422 
    1523  /** 
    16    * applies the rule to the given situation and returns a rule application result, if this was 
    17    * successful 
     24   * <p> 
     25   * applies the rule to the given parent node. The provided builder and node factory are used 
     26   * to create substructures in the task tree for the identified temporal relationships. The 
     27   * finalize parameter is used to command the rule to finish rule applications, in the case it 
     28   * is known that no further data will be available.  
     29   * </p> 
     30   * <p> 
     31   * The returned rule application result is null, if the rule can not be applied, i.e. it does not 
     32   * detect a temporal relationship. It returns a rule application result with a status 
     33   * {@link RuleApplicationStatus#RULE_APPLICATION_FINISHED} if the rule was applied. The result 
     34   * contains all newly created parent nodes. It returns a rule application result with status 
     35   * {@link RuleApplicationStatus#RULE_APPLICATION_FEASIBLE} if the rule would be applicable if 
     36   * further children would be available in the parent node. This status MUST not be returned if  
     37   * the finalize parameter is true. In this case the rule must be applied or not.  
     38   * </p> 
     39   *  
     40   * @param parent      the parent node with the children to apply the rule on 
     41   * @param builder     the builder to be used for creating substructures for the identified 
     42   *                    temporal relationships 
     43   * @param nodeFactory the node factory to be used for creating substructures for the identified 
     44   *                    temporal relationships 
     45   * @param finalize    true, if the rule shall not expect further children to come and that it 
     46   *                    should therefore be applied in any case 
     47   *                     
     48   * @return the rule application result as described. 
    1849   */ 
    19   public RuleApplicationResult apply(ITaskTreeNode        parent, 
    20                                      ITaskTreeBuilder     builder, 
    21                                      ITaskTreeNodeFactory nodeFactory, 
    22                                      boolean              finalize); 
     50  RuleApplicationResult apply(ITaskTreeNode        parent, 
     51                              ITaskTreeBuilder     builder, 
     52                              ITaskTreeNodeFactory nodeFactory, 
     53                              boolean              finalize); 
    2354   
    2455} 

  • trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/temporalrelation/TemporalRelationshipRuleManager.java

    r805 r809  
    1313 
    1414/** 
    15  * TODO comment 
     15 * <p> 
     16 * This class is responsible for applying temporal relationship rules on a task tree. Through this, 
     17 * a flat task tree is restructured to have more depth but to include more temporal relationships 
     18 * between task tree nodes which are not only a major sequence. I.e. through the application of 
     19 * rule iterations and selections of task tree nodes are detected. Which kind of temporal relations 
     20 * between task tree nodes are detected depends on the {@link TemporalRelationshipRule}s known to 
     21 * this class. 
     22 * </p> 
     23 * <p>The class holds references to the appropriate {@link TemporalRelationshipRule}s and calls 
     24 * their {@link TemporalRelationshipRule#apply(ITaskTreeNode, ITaskTreeBuilder, ITaskTreeNodeFactory, boolean)} 
     25 * method for each node in the task tree it is needed for. The general behavior of this class is 
     26 * the following: 
     27 * <ol> 
     28 *   <li> 
     29 *     An instance of this class is created using the constructor and calling the 
     30 *     {@link #init()} method afterwards 
     31 *   </li> 
     32 *   <li> 
     33 *     then the {@link #applyRules(ITaskTreeNode, ITaskTreeBuilder, ITaskTreeNodeFactory, boolean)} 
     34 *     method is called for a so far unstructured task tree node 
     35 *   </li> 
     36 *   <li> 
     37 *     the class iterates its internal list of rules and calls their 
     38 *     {@link TemporalRelationshipRule#apply(ITaskTreeNode, ITaskTreeBuilder, ITaskTreeNodeFactory, boolean)} 
     39 *     method. 
     40 *   </li> 
     41 *   <li> 
     42 *     the class evaluates the rule application result 
     43 *     <ul> 
     44 *       <li> 
     45 *         if a rule returns a rule application result that is null, the next rule is tried 
     46 *       </li> 
     47 *       <li> 
     48 *         if a rule returns that it would be feasible if more data was available and the rule 
     49 *         application shall not be finalized (see finalize parameter of the applyRules method) 
     50 *         the rule application is broken up  
     51 *       </li> 
     52 *       <li> 
     53 *         if a rule returns, that it was applied, the same rule is applied again until it returns 
     54 *         null or feasible. For each newly created parent node provided in the rule application 
     55 *         result, the {@link #applyRules(ITaskTreeNode, ITaskTreeBuilder, ITaskTreeNodeFactory, boolean)} 
     56 *         method is called. 
     57 *       </li> 
     58 *     </ul> 
     59 *   </li> 
     60 * </ol> 
     61 * Through this, all rules are tried to be applied at least once to the provided parent node and 
     62 * all parent nodes created during the rule application. 
     63 * </p> 
    1664 *  
    17  * @version $Revision: $ $Date: 12.02.2012$ 
    18  * @author 2012, last modified by $Author: patrick$ 
     65 * @author Patrick Harms 
    1966 */ 
    2067public class TemporalRelationshipRuleManager { 
    2168     
    22     /** */ 
     69    /** 
     70     * <p> 
     71     * the node equality manager needed by the rules to compare task tree nodes with each other 
     72     * </p> 
     73     */ 
    2374    private NodeEqualityRuleManager nodeEqualityRuleManager; 
    2475 
    25     /** */ 
    26     private List<TemporalRelationshipRule> ruleIndex = new ArrayList<TemporalRelationshipRule>(); 
    27  
    28     /** 
    29      * TODO: comment 
    30      *  
     76    /** 
     77     * <p> 
     78     * the temporal relationship rule known to the manager. The rules are applied in the order 
     79     * they occur in this list. 
     80     * </p> 
     81     */ 
     82    private List<TemporalRelationshipRule> rules = new ArrayList<TemporalRelationshipRule>(); 
     83 
     84    /** 
     85     * <p> 
     86     * initialize the manager with a node equality rule manager to be used by the known rules 
     87     * for task tree node comparison. 
     88     * </p> 
    3189     */ 
    3290    public TemporalRelationshipRuleManager(NodeEqualityRuleManager nodeEqualityRuleManager) { 
    … …  
    3694 
    3795    /** 
    38      * TODO: comment 
     96     * <p> 
     97     * initialized the temporal relationship rule manager by instantiating the known rules and 
     98     * providing them with a reference to the node equality manager or other information they need. 
     99     * </p> 
     100     */ 
     101    public void init() { 
     102        rules.add(new DefaultGuiElementSequenceDetectionRule()); 
     103        rules.add(new DefaultEventTargetSequenceDetectionRule()); 
     104        rules.add(new TrackBarSelectionDetectionRule(nodeEqualityRuleManager)); 
     105        rules.add(new DefaultGuiEventSequenceDetectionRule()); 
     106         
     107        rules.add(new DefaultIterationDetectionRule 
     108                      (nodeEqualityRuleManager, NodeEquality.LEXICALLY_EQUAL)); 
     109        rules.add(new DefaultIterationDetectionRule 
     110                      (nodeEqualityRuleManager, NodeEquality.SYNTACTICALLY_EQUAL)); 
     111        rules.add(new DefaultIterationDetectionRule 
     112                      (nodeEqualityRuleManager, NodeEquality.SEMANTICALLY_EQUAL)); 
     113    } 
     114 
     115    /** 
     116     * <p> 
     117     * applies the known rules to the provided parent node. For the creation of further nodes, 
     118     * the provided builder and node factory are utilized. If the finalize parameter is true, the 
     119     * rule application is finalized as far as possible without waiting for further data. If it is 
     120     * false, the rule application is broken up at the first rule returning, that its application 
     121     * would be feasible.  
     122     * </p> 
    39123     *  
    40      */ 
    41     public void init() { 
    42         ruleIndex.add(new DefaultGuiElementSequenceDetectionRule()); 
    43         ruleIndex.add(new DefaultEventTargetSequenceDetectionRule()); 
    44         ruleIndex.add(new TrackBarSelectionDetectionRule(nodeEqualityRuleManager)); 
    45         ruleIndex.add(new DefaultGuiEventSequenceDetectionRule()); 
    46          
    47         ruleIndex.add(new DefaultIterationDetectionRule 
    48                           (nodeEqualityRuleManager, NodeEquality.LEXICALLY_EQUAL)); 
    49         ruleIndex.add(new DefaultIterationDetectionRule 
    50                           (nodeEqualityRuleManager, NodeEquality.SYNTACTICALLY_EQUAL)); 
    51         ruleIndex.add(new DefaultIterationDetectionRule 
    52                           (nodeEqualityRuleManager, NodeEquality.SEMANTICALLY_EQUAL)); 
    53     } 
    54  
    55     /** 
    56      * returns true, if there is a rule that matches the current situation and if, therefore, a new 
    57      * temporal relationship has been added to the tree. 
    58      *  
    59      * @param parent 
    60      * @param newChild 
    61      * @return 
     124     * @param parent       the parent node to apply the rules on 
     125     * @param builder      the task tree builder to be used for linking task tree nodes with each 
     126     *                     other 
     127     * @param nodeFactory  the node factory to be used for instantiating new task tree nodes. 
     128     * @param finalize     used to indicate, if the rule application shall break up if a rule would 
     129     *                     be feasible if further data was available, or not. 
    62130     */ 
    63131    public void applyRules(ITaskTreeNode        parent, 
    … …  
    70138 
    71139    /** 
    72      * returns true, if there is a rule that matches the current situation and if, therefore, a new 
    73      * temporal relationship has been added to the tree. 
     140     * <p> 
     141     * applies the known rules to the provided parent node. For the creation of further nodes, 
     142     * the provided builder and node factory are utilized. If the finalize parameter is true, the 
     143     * rule application is finalized as far as possible without waiting for further data. If it is 
     144     * false, the rule application is broken up at the first rule returning, that its application 
     145     * would be feasible. The method calls itself for each parent node created through the rule 
     146     * application. In this case, the finalize parameter is always true. 
     147     * </p> 
    74148     *  
    75      * @param parent 
    76      * @param newChild 
    77      * @return 
     149     * @param parent       the parent node to apply the rules on 
     150     * @param builder      the task tree builder to be used for linking task tree nodes with each 
     151     *                     other 
     152     * @param nodeFactory  the node factory to be used for instantiating new task tree nodes. 
     153     * @param finalize     used to indicate, if the rule application shall break up if a rule would 
     154     *                     be feasible if further data was available, or not. 
     155     * @param logIndent    simply used for loggin purposes to indent the log messages depending 
     156     *                     on the recursion depth of calling this method. 
    78157     */ 
    79158    private int applyRules(ITaskTreeNode        parent, 
    … …  
    87166        int noOfRuleApplications = 0; 
    88167 
    89         for (TemporalRelationshipRule rule : ruleIndex) { 
     168        for (TemporalRelationshipRule rule : rules) { 
    90169            RuleApplicationResult result; 
    91170            do { 
    … …  
    130209 
    131210    /** 
    132    * 
    133    */ 
     211     * 
     212     */ 
    134213    /* 
    135214     * private void dumpTask(TaskTreeNode task, String indent) { System.err.print(indent); 
Note: See TracChangeset for help on using the changeset viewer.