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
File:
1 edited

Legend:

Unmodified
Added
Removed

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