- * TODO comment + * This class implements the major rule for creating task trees based on a set of recorded + * user sessions. For this, it first harmonizes all tasks. This eases later comparison. Then it + * searches the sessions for iterations and replaces them accordingly. Then it searches for sub + * sequences being the longest and occurring most often. For each found sub sequence, it replaces + * the occurrences by creating appropriate {@link ISequence}s. Afterwards, again searches for + * iterations and then again for sub sequences until no more replacements are done. + *
+ *+ * For determining the longest sequence occurring most often, the implementation uses a + * {@link Trie}. The depth of the tree is initially 3. If the algorithm has a longest sequence + * occurring most often whose length is equal to the depth of the trie, it recalculates the trie + * with an increased depth. *
* @@ -54,5 +66,5 @@ ** the task factory to be used for creating substructures for the temporal - * relationships identified during rule + * relationships identified during rul application *
*/ @@ -68,5 +80,6 @@ /** *- * the task comparator to be used for comparing tasks for preparation + * the task handling strategy to be used for comparing tasks for preparation, i.e., before + * the tasks are harmonized *
*/ @@ -75,6 +88,6 @@ /** *- * the task comparator to be used for comparing tasks during iteration detection an trie - * generation + * the task handling strategy to be used for comparing tasks during iteration detection an trie + * generation, i.e., after the tasks are harmonized *
*/ @@ -83,7 +96,12 @@ /** *- * instantiates the rule and initializes it with a task equality rule manager and the minimal - * task equality identified sublist must have to consider them as iterated. + * instantiates the rule and initializes it with a task equality to be considered when + * comparing tasks as well as a task factory and builder to be used for creating task + * structures. *
+ * + * @param minimalTaskEquality the task equality to be considered when comparing tasks + * @param taskFactory the task factory to be used for creating substructures + * @param taskBuilder the task builder to be used for creating substructures */ SequenceForTaskDetectionRule(TaskEquality minimalTaskEquality, @@ -151,8 +169,11 @@ /** *- * TODO: comment + * harmonizes the event task instances by unifying tasks. This is done, as initially the + * event tasks being equal with respect to the considered task equality are distinct objects. + * The comparison of these distinct objects is more time consuming than comparing the object + * references. *
* - * @param appData + * @param appData the rule application data combining all data used for applying this rule */ private void harmonizeEventTaskInstancesModel(RuleApplicationData appData) { @@ -194,5 +215,12 @@ /** - * @param appData + *+ * searches for direct iterations of single tasks in all sequences and replaces them with + * {@link IIteration}s, respectively appropriate instances. Also all single occurrences of + * a task that is iterated somewhen are replaced with iterations to have again an efficient + * way for task comparisons. + *
+ * + * @param appData the rule application data combining all data used for applying this rule */ private void detectAndReplaceIterations(RuleApplicationData appData) { @@ -213,5 +241,12 @@ /** - * + *+ * searches the provided sessions for task iterations. If a task is iterated, it is added + * to the returned set. + *
+ * + * @param the session to search for iterations in + * + * @return a set of tasks being iterated somewhere */ private Set+ * replaces all occurrences of all tasks provided in the set with iterations + *
* + * @param iteratedTasks the tasks to be replaced with iterations + * @param sessions the sessions in which the tasks are to be replaced + * @param appData the rule application data combining all data used for applying this rule */ private void replaceIterationsOf(Set+ * TODO clarify why this is done + *
*/ private void harmonizeIterationInstancesModel(IIteration iteration, @@ -345,5 +388,6 @@ /** - * @param appData + * TODO go on commenting + * @param appData the rule application data combining all data used for applying this rule */ private void detectAndReplaceTasks(RuleApplicationData appData) { @@ -365,5 +409,5 @@ /** - * @return + * @param appData the rule application data combining all data used for applying this rule */ private void getSequencesOccuringMostOften(RuleApplicationData appData) { @@ -462,6 +506,5 @@ /** - * @param parent - * @return + * @param appData the rule application data combining all data used for applying this rule */ private void createNewTrie(RuleApplicationData appData) { @@ -483,5 +526,5 @@ /** - * @param appData + * @param appData the rule application data combining all data used for applying this rule */ private void replaceSequencesOccurringMostOften(RuleApplicationData appData) { Index: /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskHandlingStrategy.java =================================================================== --- /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskHandlingStrategy.java (revision 1400) +++ /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskHandlingStrategy.java (revision 1401) @@ -17,5 +17,4 @@ import de.ugoe.cs.autoquest.tasktrees.taskequality.TaskEquality; import de.ugoe.cs.autoquest.tasktrees.treeifc.ITaskInstance; -import de.ugoe.cs.autoquest.usageprofiles.DefaultSymbolMap; import de.ugoe.cs.autoquest.usageprofiles.SymbolComparator; import de.ugoe.cs.autoquest.usageprofiles.SymbolMap; @@ -24,5 +23,9 @@ /** *- * TODO comment + * concrete implementation of a symbol strategy required in the creation of a + * {@link de.ugoe.cs.autoquest.usageprofiles.Trie}. The strategy can be parameterized with a + * considered task equality. It uses task instance comparators to perform task comparison. + * It creates task specific symbol maps, which are {@link TaskSymbolIdentityMap} and + * {@link TaskSymbolBucketedMap} depending on the level of considered task equality. *
* @@ -35,10 +38,14 @@ /** - * + *+ * the level of task equality considered in this task handling strategy + *
*/ private TaskEquality consideredEquality; /** - * + *+ * the comparator used for task comparisons + *
*/ private TaskInstanceComparator comparator; @@ -46,8 +53,8 @@ /** *- * TODO: comment + * initializes this strategy with a task equality to be considered for task comparisons *
* - * @param consideredEquality + * @param consideredEquality the task equality to be considered for task comparisons */ public TaskHandlingStrategy(TaskEquality consideredEquality) { @@ -72,8 +79,7 @@ /** *- * TODO: comment + * convenience method to have a correctly typed return value as alternative to + * {@link #getSymbolComparator()}; *
- * - * @return */ public TaskInstanceComparator getTaskComparator() { @@ -95,10 +101,10 @@ /* (non-Javadoc) - * @see de.ugoe.cs.autoquest.usageprofiles.SymbolStrategy#copySymbolMap(de.ugoe.cs.autoquest.usageprofiles.SymbolMap) + * @see de.ugoe.cs.autoquest.usageprofiles.SymbolStrategy#copySymbolMap(SymbolMap) */ @Override public+ * symbol comparator implementation for task instances considering to task instances as equal if + * they refer to the identical task object (comparison of object references). + *
*/ class TaskIdentityComparator extends TaskInstanceComparator { @@ -28,8 +31,6 @@ /** *- * TODO: comment + * initializes the parent class with the task equality {@link TaskEquality#IDENTICAL}. *
- * - * @param minimalNodeEquality */ public TaskIdentityComparator() { Index: /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskInstanceComparator.java =================================================================== --- /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskInstanceComparator.java (revision 1400) +++ /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskInstanceComparator.java (revision 1401) @@ -26,5 +26,11 @@ /** - * TODO comment + *+ * implementation of a symbol comparator for task instances. Internally, it uses comparison buffers + * to prevent comparing two tasks or task instances several times. It internally instantiates + * comparers being the implementation strategy of the comparisons required for a specific level + * of task equality. The comparers internally use the {@link TaskEqualityRuleManager} for + * performing comparisons. + *
*/ public class TaskInstanceComparator implements SymbolComparator+ * initializes the comparator with a considered task equality level + *
+ * + * @param minimalTaskEquality the considered task equality level + */ + public TaskInstanceComparator(TaskEquality minimalTaskEquality) { + this.minimalTaskEquality = minimalTaskEquality; init(); } @@ -68,5 +90,12 @@ /** - * + *+ * returns true, if this comparator considers the provided tasks as equal, false else + *
+ * + * @param task1 the first task to compare + * @param task2 the second task to compare + * + * @return as described */ public boolean equals(ITask task1, ITask task2) { @@ -100,5 +129,12 @@ /** - * + *+ * returns true, if this comparator considers the provided tasks as lexically equal, false else + *
+ * + * @param task1 the first task to compare + * @param task2 the second task to compare + * + * @return as described */ public boolean areLexicallyEqual(ITask task1, ITask task2) { @@ -127,7 +163,6 @@ /** *- * TODO: comment - *
- * + * can be called externally to clear the internal comparison buffers + * */ public void clearBuffers() { @@ -137,21 +172,25 @@ /** - * + *+ * initializes the comparator with comparers depending on the different comparison levels as + * well as with the required comparison buffers. Comparers and buffers for lexical comparison + * may be reused if the considered equality level is also lexical. + *
*/ private void init() { - if (minimalNodeEquality == TaskEquality.LEXICALLY_EQUAL) { + if (minimalTaskEquality == TaskEquality.LEXICALLY_EQUAL) { comparer = new LexicalComparer(); } - else if (minimalNodeEquality == TaskEquality.SYNTACTICALLY_EQUAL) { + else if (minimalTaskEquality == TaskEquality.SYNTACTICALLY_EQUAL) { comparer = new SyntacticalComparer(); } - else if (minimalNodeEquality == TaskEquality.SEMANTICALLY_EQUAL) { + else if (minimalTaskEquality == TaskEquality.SEMANTICALLY_EQUAL) { comparer = new SemanticalComparer(); } else { - comparer = new DefaultComparer(this.minimalNodeEquality); - } - - if (minimalNodeEquality == TaskEquality.LEXICALLY_EQUAL) { + comparer = new DefaultComparer(this.minimalTaskEquality); + } + + if (minimalTaskEquality == TaskEquality.LEXICALLY_EQUAL) { lexicalComparer = comparer; lexicalEqualityBuffer = equalityBuffer; @@ -175,10 +214,19 @@ /** - * + *+ * interface for internally used comparers containing only a compare method + *
*/ private static interface Comparer { /** + *+ * returns true, if this comparator considers the provided tasks as equal, false else + *
* + * @param task1 the first task to compare + * @param task2 the second task to compare + * + * @return as described */ boolean compare(ITask task1, ITask task2); @@ -186,10 +234,12 @@ /** - * + *+ * comparer that performs comparisons only on the lexical level + *
*/ private static class LexicalComparer implements Comparer { - /** - * + /* (non-Javadoc) + * @see Comparer#compare(ITask, ITask) */ public boolean compare(ITask task1, ITask task2) { @@ -199,10 +249,13 @@ /** + *+ * comparer that performs comparisons only on the syntactical level + *
* */ private static class SyntacticalComparer implements Comparer { - /** - * + /* (non-Javadoc) + * @see Comparer#compare(ITask, ITask) */ public boolean compare(ITask task1, ITask task2) { @@ -212,10 +265,12 @@ /** - * + *+ * comparer that performs comparisons only on the semantical level + *
*/ private static class SemanticalComparer implements Comparer { - /** - * + /* (non-Javadoc) + * @see Comparer#compare(ITask, ITask) */ public boolean compare(ITask task1, ITask task2) { @@ -225,5 +280,7 @@ /** - * + *+ * comparer that performs comparisons only on the provided level + *
*/ private static class DefaultComparer implements Comparer { @@ -231,22 +288,24 @@ /** *- * the minimal task equality two identified sublists need to have to consider them as equal + * the minimal task equality considered by this comparer *
*/ - private TaskEquality minimalNodeEquality; + private TaskEquality minimalTaskEquality; /** - * - */ - public DefaultComparer(TaskEquality minimalNodeEquality) { - this.minimalNodeEquality = minimalNodeEquality; - } - - /** - * + *+ * initializes this comparer with the task equality to be considered + *
+ */ + public DefaultComparer(TaskEquality minimalTaskEquality) { + this.minimalTaskEquality = minimalTaskEquality; + } + + /* (non-Javadoc) + * @see Comparer#compare(ITask, ITask) */ public boolean compare(ITask task1, ITask task2) { return TaskEqualityRuleManager.getInstance().areAtLeastEqual - (task1, task2, minimalNodeEquality); + (task1, task2, minimalTaskEquality); } } Index: /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskInstanceTrie.java =================================================================== --- /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskInstanceTrie.java (revision 1400) +++ /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskInstanceTrie.java (revision 1401) @@ -29,5 +29,10 @@ /** *- * TODO comment + * This trie implementation is a performance optimization for generating task trees. It does not + * create a full trie but adds only those subsequences having a chance of occurring most often. + * For this, it initially counts the number of occurrences of each task instance. Then, during + * training, it regularly determines the number of the currently most often occurring sequence. If + * this number is higher than the count of a task instance to be trained, the task instance is + * skipped the not added to the trie. *
* @@ -41,5 +46,5 @@ /** *- * the task comparator to be used for comparing tasks + * the task handling strategy to be used for comparing tasks *
*/ @@ -48,8 +53,8 @@ /** *- * TODO: comment + * instantiated the trie with the task handling strategy to be used *
* - * @param taskComparator2 + * @param taskStrategy the task handling strategy to be used for comparing tasks */ public TaskInstanceTrie(TaskHandlingStrategy taskStrategy) { @@ -59,5 +64,11 @@ /** - * + *+ * trains this trie with the provided user sessions up to the provided maximum depth using + * the optimization described in the description of this class. + *
+ * + * @param userSessions the sessions for which this trie is to be trained + * @param maxOrder the depth of the trie */ public void trainSessions(List+ * internally used convenience method for implementing the training optimization + *
*/ private void train(IUserSession userSession, @@ -133,11 +146,9 @@ int counterRecheckAt) { - List- * TODO: comment + * determines the current maximum count of sequences of a minimal length of two. Task instances + * occuring more seldom do not have to be considered anymore *
* - * @return + * @return the current maximum count of sequences of a minimal length of two */ private int getCurrentSequenceMaxCount() { @@ -193,4 +205,8 @@ /** + *+ * trie processor identifying the current maximum count of sequences of a minimal length of two + *
+ * * @author Patrick Harms */ @@ -198,5 +214,7 @@ /** - * + *+ * the current maximum count + *
*/ private int currentCount = 0; @@ -219,5 +237,7 @@ /** - * + *+ * returns the current maximum count + *
*/ private int getMaxCount() { @@ -228,4 +248,8 @@ /** + *+ * counter object to be able to call something by the counters reference + *
+ * * @author Patrick Harms */ Index: /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskSymbolIdentityMap.java =================================================================== --- /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskSymbolIdentityMap.java (revision 1400) +++ /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/temporalrelation/TaskSymbolIdentityMap.java (revision 1401) @@ -25,5 +25,6 @@ /** *- * TODO comment + * symbol map implementation for task instances considering two task instances as equal if their + * tasks are identical *
* @@ -36,10 +37,14 @@ /** - * + *+ * internally used map for implementing the symbol map interface + *
*/ private Map+ * mapping between the tasks and the real symbols stored in the map, i.e. the task instances + *
*/ private Map- * TODO: comment + * initializes this map *
- * - * @param other */ public TaskSymbolIdentityMap() { @@ -59,8 +62,8 @@ /** *- * TODO: comment + * copy constructor *
* - * @param other + * @param other the map to be copied */ public TaskSymbolIdentityMap(SymbolMap