+ * Builder for task models. Can be used to create and edit task models. May perform integrity + * checks, though they may be incomplete as the integrity of a task model can not be ensured during + * creation. + *
*/ public interface ITaskBuilder { /** - * @param taskInstance - * @param child + *+ * adds a child to a task instance. May ensure, that the child is a valid child considering + * the task model of the parent. In that case, an IllegalArgumentException is thrown. + *
+ * + * @param taskInstance the instance of add the child to + * @param child the child to be added + * + * @throws IllegalArgumentException as described */ void addChild(ITaskInstance taskInstance, ITaskInstance child) throws IllegalArgumentException; @@ -31,112 +39,187 @@ /** *- * TODO: comment + * adds a task instance to a user session *
* - * @param session - * @param taskInstance + * @param session the session to add the task instance to + * @param taskInstance the task instance to add */ void addExecutedTask(IUserSession session, ITaskInstance taskInstance); /** - * - * @param parent - * @param i + *+ * adds a task instance to a task instance list + *
+ * + * @param taskInstanceList the list to add the task instance to + * @param taskInstance the task instance to add */ void addTaskInstance(ITaskInstanceList taskInstanceList, ITaskInstance taskInstance); /** - * - * @param parent - * @param i - */ - void addTaskInstance(ITaskInstanceList taskInstanceList, int index, ITaskInstance taskInstance); - - /** - * - * @param parent - * @param i - */ - void setTaskInstance(ITaskInstanceList taskInstanceList, int index, ITaskInstance taskInstance); - - /** - *- * TODO: comment - *
- * - * @param instance2 - * @param task + *+ * adds a task instance to a task instance list at a specific position. Subsequent task + * instances will be moved one index forward + *
+ * + * @param taskInstanceList the list to add the task instance to + * @param index the index of the task instance to add + * @param taskInstance the task instance to add + * + * @throws IndexOutOfBoundsException if the index is invalid + */ + void addTaskInstance(ITaskInstanceList taskInstanceList, int index, ITaskInstance taskInstance) + throws IndexOutOfBoundsException; + + /** + *+ * sets a task instance in a task instance list at a specific position + *
+ * + * @param taskInstanceList the list to set the task instance in + * @param index the index of the task instance to replace + * @param taskInstance the replacement for the task instance at the index + * + * @throws IndexOutOfBoundsException if the index is invalid + */ + void setTaskInstance(ITaskInstanceList taskInstanceList, int index, ITaskInstance taskInstance) + throws IndexOutOfBoundsException; + + /** + *+ * sets the task model of a task instance + *
+ * + * @param taskInstance the task instance to set the task model for + * @param task the task model of the instance */ void setTask(ITaskInstance taskInstance, ITask task); /** - * + *+ * adds a child task to the end of a sequence + *
+ * + * @param parent the sequence to add the child to + * @param child the child to be added */ void addChild(ISequence parent, ITask child); /** - * - */ - void addChild(ISequence parent, int index, ITask child); - - /** - * - * @param parent - * @param i - */ - void setChild(ISequence parent, int index, ITask child); - - /** - * @param sequence - * @param task + *+ * adds a child task to a specific index of a sequence + *
+ * + * @param parent the sequence to add the child to + * @param index the index to set the child at + * @param child the child to be added + * + * @throws IndexOutOfBoundsException if the index is invalid + */ + void addChild(ISequence parent, int index, ITask child) + throws IndexOutOfBoundsException; + + /** + *+ * replaces the child task of a sequence at a specific position + *
+ * + * @param parent the sequence to replace the child in + * @param index the index to replace the child at + * @param child the child to be added + * + * @throws IndexOutOfBoundsException if the index is invalid + */ + void setChild(ISequence parent, int index, ITask child) + throws IndexOutOfBoundsException; + + /** + *+ * adds a child task to a selection + *
+ * + * @param parent the selection to add the child to + * @param child the child to be added */ void addChild(ISelection parent, ITask child); /** - * - * @param iteration - * @param newChild - */ - void setMarkedTask(IIteration iteration, ITask newChild); - - /** - * - * @param optional - * @param newChild - */ - void setMarkedTask(IOptional optional, ITask newChild); - - /** - * - * @param parent - * @param i - */ - void removeChild(ISequence parent, int index); - - /** - * - * @param parent - * @param i + *+ * sets the child task of an iteration + *
+ * + * @param parent the iteration to set the child of + * @param child the child to be set + */ + void setMarkedTask(IIteration iteration, ITask child); + + /** + *+ * sets the child task of an optional + *
+ * + * @param parent the optional to set the child of + * @param child the child to be set + */ + void setMarkedTask(IOptional optional, ITask child); + + /** + *+ * removes the child of a sequence at a specific position + *
+ * + * @param parent the sequence of which the child must be removed + * @param index the index of the child to be removed + * + * @throws IndexOutOfBoundsException if the index is invalid + */ + void removeChild(ISequence parent, int index) + throws IndexOutOfBoundsException; + + /** + *+ * removes a child of a selection. Ignores the call, if the child is not found + * (comparison using equals). + *
+ * + * @param parent the selection of which the child must be removed + * @param child the child to be removes */ void removeChild(ISelection parent, ITask child); /** - * - * @param parent - * @param i - */ - void removeTaskInstance(ITaskInstanceList taskInstanceList, int index); - - /** - * - * @param parent - * @param i + *+ * removes the entry of a task instance list at a specific position + *
+ * + * @param taskInstanceList the task instance list of which the entry must be removed + * @param index the index of the entry to be removed + * + * @throws IndexOutOfBoundsException if the index is invalid + */ + void removeTaskInstance(ITaskInstanceList taskInstanceList, int index) + throws IndexOutOfBoundsException; + + /** + *+ * replaces a child of a selection. Throws an IllegalArgumentException if the child is not + * found (comparison using equals). + *
+ * + * @param parent the selection of which the child must be replace + * @param oldChild the child to replace + * @param newChild the replacement for the child + * + * @throws as described */ void replaceChild(ISelection parent, ITask oldChild, ITask newChild); /** - * - * @param parent - * @param i + *+ * sets the description of a task + *
+ * + * @param task the task to set the description of + * @param description the new description of the task */ void setDescription(ITask task, String description); Index: /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskFactory.java =================================================================== --- /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskFactory.java (revision 1190) +++ /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskFactory.java (revision 1191) @@ -21,65 +21,97 @@ /** - * TODO comment + *+ * factory for the different task types + *
* - * @version $Revision: $ $Date: 21.02.2012$ - * @author 2012, last modified by $Author: patrick$ + * @author Patrick Harms */ public interface ITaskFactory { /** + *+ * creates a new event task with the given type and target + *
* - * @param eventType - * @param eventTarget - * @return + * @param eventType the type of the event represented by the task + * @param eventTarget the target of the event represented by the task + * + * @return the event task */ IEventTask createNewEventTask(IEventType eventType, IEventTarget eventTarget); /** + *+ * creates a new empty sequence + *
* - * @return + * @return the sequence */ ISequence createNewSequence(); /** + *+ * creates a new empty iteration + *
* - * @return + * @return the iteration */ IIteration createNewIteration(); /** + *+ * creates a new empty optional + *
* - * @return + * @return the optional */ IOptional createNewOptional(); /** + *+ * creates a new empty selection + *
* - * @return + * @return the selection */ ISelection createNewSelection(); /** + *+ * creates a new task instance with the given task as its model + *
* - * @return + * @param task the model of the task instance to be created + * + * @return the task instance */ ITaskInstance createNewTaskInstance(ITask task); /** - * - * @return + *+ * creates a new empty task instance list + *
+ * + * @return the task instance list */ ITaskInstanceList createNewTaskInstanceList(); /** + *+ * creates a new empty user session + *
* - * @return + * @return the user session */ IUserSession createUserSession(); /** + *+ * creates a task model based on the provided user sessions + *
* - * @param rootSequence - * @return + * @param userSessions the session based on which the task model shall be created + * + * @return the task model */ ITaskModel createTaskModel(List+ * yet more or less unused, this class will in the future provided extended information about a + * specific task, such as statistics about task occurrences, etc. + *
* - * @version $Revision: $ $Date: 21.02.2012$ - * @author 2012, last modified by $Author: patrick$ + * @author Patrick Harms */ public interface ITaskInfo extends Serializable { /** + *+ * returns the task to which these infos belong + *
* + * @return as described */ public ITask getTask(); Index: /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskVisitor.java =================================================================== --- /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskVisitor.java (revision 1190) +++ /trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskVisitor.java (revision 1191) @@ -26,21 +26,21 @@ /** - * - */ + * + */ public void visit(IEventTask event); /** - * - */ + * + */ public void visit(IIteration iteration); /** - * - */ + * + */ public void visit(ISelection selection); /** - * - */ + * + */ public void visit(ISequence sequence);