+ * a task instance represents the execution of a specific task within a user session. A task + * instance is always related to the task that was executed. A task instance may have children + * but only if its related task allows to have children. For example, if the represented task is + * a sequence then task instance has children and these are instances of the tasks being the + * children of the related sequence. + *
+ *+ * An instance of a sequence has the same number of children as the related sequence. An instance + * of a selection has only one child which is an instance of exactly one variant contained in the + * related selection. An instance of an iteration has zero or more instances of the same task + * as children where the task is the child of the related iteration. An instance of an optional + * has zero or one child where the task related to child is the child of the optional. A task + * instance related to an event task does not have children. + *
* - * @version $Revision: $ $Date: $ - * @author 2011, last modified by $Author: $ + * @author Patrick Harms */ public interface ITaskInstance extends ITaskInstanceList { /** - * + *+ * returns the children of the task instance if any. See class description for how many + * children can be expected. May return null. + *
+ * + * @return as described */ public List+ * returns the task related to the instance. + *
+ * + * @return as described */ public ITask getTask(); /** - * + *+ * compares an instance to another one. Returns true if both instances are the same, i.e. not + * only the related task is equal but also all children and further characteristics of the + * task instance + *
+ * + * @param taskInstance the instance to compare to + * + * @return as described */ public boolean equals(ITaskInstance taskInstance); /** - * + *+ * returns a hash code for the task instance to be able to put it into hash maps + *
+ * + * @return as described */ public int hashCode(); /** - * + *+ * clones a task instance by creating exact clones of each contained child instance as well + * as the related task. Furthermore, all other non transient information of the task + * instance must be cloned. + *
+ * + * @return a clone of the task instance */ public ITaskInstance clone(); Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskInstanceList.java =================================================================== --- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskInstanceList.java (revision 1176) +++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskInstanceList.java (revision 1177) @@ -19,5 +19,6 @@ /** *- * TODO comment + * represents a serializable, clonable, iterable representation of a read only list of task + * instances. The list is ordered. It does not provide methods for changing it. *
* @@ -27,15 +28,31 @@ /** - * + *+ * returns the task instance at the position with the given index. May throw an exception + * if the index is invalid. + *
+ * + * @param index the index of the task instance to be returned + * + * @return the task instance at the given index */ public ITaskInstance get(int index); /** - * + *+ * returns the size of the list, i.e. the number of task instances in the list + *
+ * + * @return as described */ public int size(); /** - * + *+ * clones a task instance list by creating exact clones of each contained instance in their + * order + *
+ * + * @return a clone of the task instance list */ public ITaskInstanceList clone(); Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/IUserSession.java =================================================================== --- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/IUserSession.java (revision 1176) +++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/IUserSession.java (revision 1177) @@ -19,5 +19,7 @@ /** *- * TODO comment + * A user session represents task executions, i.e. a task instances of a specific user that were + * executed in a coherent manner. Therefore, they are an ordered list of task instances where + * the order denotes the order of the task executions. *
* @@ -27,20 +29,40 @@ /** - * + *+ * returns the list of task instances executed in the represented session. + *
+ * + * @return as described */ public List+ * compares the user session with another one. Two user sessions are only equal, if they + * contain the same number of task instances and if each task instance at each position is + * equal to the respective other session. + *
+ * + * @param userSession the session to compare the session to + * + * @return true if both sessions are equal, false else */ public boolean equals(IUserSession userSession); /** - * + *+ * returns a hash code for the session to be able to store the session in a hash map. + *
+ * + * @return as described */ public int hashCode(); /** - * + *+ * clones a user session by creating exact clones of each contained instance in their order + *
+ * + * @return a clone of the session */ public IUserSession clone();