- * yet more or less unused, this class will in the future provide extended information about a - * specific task, such as statistics about task occurrences, etc. + * Provides extended information about a specific task, such as statistics about task occurrences, + * etc. It contains measures for different metrics determined for a task. *
* @@ -38,10 +38,74 @@ /** *- * returns the number of times a task occurred + * returns all available measures *
* * @return as described */ - public int getCount(); + public IMeasure[] getMeasures(); + + /** + *+ * returns the value of the measure identified through the given metric + *
+ * + * @param metric the metric for which the value is to be returned + * + * @return as described + */ + public int getMeasureValue(TaskMetric metric); + + /** + *+ * returns the value of the measure identified through the given metric if the task is + * observed in the given context, i.e. parent task. The result is Integer.MIN_VALUE if there + * is no value for this measure in a context. + *
+ * + * @param metric the metric for which the value is to be returned + * @param context the context for which the measure value is to be returned + * + * @return as described + */ + public int getMeasureValue(TaskMetric metric, ITask context); + + /** + *+ * represents a measure for a specific metric + *
+ * + * @author Patrick Harms + */ + public interface IMeasure { + + /** + *+ * returns the metric of the measure + *
+ * + * @return as described + */ + public TaskMetric getMetric(); + + /** + *+ * returns the value of the measure + *
+ * + * @return as described + */ + public int getValue(); + + /** + *+ * returns the value of the measure if the task was observed in a specific context, i.e. + * parent task + *
+ * + * @return as described + */ + public int getValue(ITask context); + + } } Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskModel.java =================================================================== --- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskModel.java (revision 1422) +++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskModel.java (revision 1423) @@ -22,5 +22,5 @@ ** This class represents a complete task model. A task model within AutoQUEST is usually generated - * based on user session. Therefore, the task model consists of the user sessions, the models + * based on user sessions. Therefore, the task model consists of the user sessions, the models * of the identified tasks, as well as further information about the tasks (e.g. their * occurrence count) for statistical processing. @@ -63,4 +63,14 @@ /** *
+ * returns a list of all metrics calculated by this model for the tasks and stored in the + * respective task infos + *
+ * + * @return as described + */ + public TaskMetric[] getAllMetrics(); + + /** + ** creates a deep clone of the model including all tasks and user sessions. *
@@ -69,3 +79,4 @@ */ public ITaskModel clone(); + } Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/TaskMetric.java =================================================================== --- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/TaskMetric.java (revision 1423) +++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/TaskMetric.java (revision 1423) @@ -0,0 +1,138 @@ +// Copyright 2012 Georg-August-Universität Göttingen, Germany +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package de.ugoe.cs.autoquest.tasktrees.treeifc; + +import java.text.DecimalFormat; + +/** + *+ * represents different metrics available or calculatable for tasks. Measure for the metrics + * are calculated by a task model and added to the task infos of a specific task. + *
+ * + * @author Patrick Harms + */ +public enum TaskMetric { + + COUNT("count", "number of all occurrences of the task in the model"), + DEPTH("depth", + "the maximum depth of the task, i.e., the number of children levels including the " + + "level of the task itself"), + EVENT_COVERAGE("covered events", "number of all event task instances covered by the task"), + EVENT_COVERAGE_RATIO("event coverage ratio", + "the ratio of events covered by this task in relation to all events " + + "covered by all tasks in their instances in per mille", 0.1, "%"); + + /** + *+ * the name of the metric + *
+ */ + private String name; + + /** + *+ * a human readable description of the metric + *
+ */ + private String description; + + /** + *+ * a scale applied for the metric when formatting the value + *
+ */ + private double formatScale; + + /** + *+ * the unit of the metric used when formatting the value + *
+ */ + private String formatUnit; + + /** + *+ * initializes the metric with a name and a description + *
+ */ + private TaskMetric(String name, String description) { + this.name = name; + this.description = description; + this.formatScale = 1.0; + this.formatUnit = null; + } + + /** + *+ * initializes the metric with a name and a description, as well as with a scale and a unit for + * formatting it. + *
+ */ + private TaskMetric(String name, String description, double formatScale, String formatUnit) { + this.name = name; + this.description = description; + this.formatScale = formatScale; + this.formatUnit = formatUnit; + } + + /** + *+ * returns the name of the metric + *
+ * + * @return the name of the metric + */ + public String getName() { + return name; + } + + /** + *+ * returns the human readable description of the metric + *
+ * + * @return the human readable description of the metric + */ + public String getDescription() { + return description; + } + + /** + *+ * formats the provided value of a measure of the metric using the internal format scale and + * unit. + *
+ * + * @return the formatted value depending on the scale and unit of the metric + */ + public String formatValue(int value) { + String formattedValue; + + if (formatScale != 1.0) { + double effectiveValue = formatScale * value; + formattedValue = new DecimalFormat( "#,##0.0;(#)").format(effectiveValue); + } + else { + formattedValue = Integer.toString(value); + } + + if (formatUnit != null) { + formattedValue += formatUnit; + } + + return formattedValue; + } +} Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeimpl/TaskInfo.java =================================================================== --- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeimpl/TaskInfo.java (revision 1422) +++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeimpl/TaskInfo.java (revision 1423) @@ -15,6 +15,10 @@ package de.ugoe.cs.autoquest.tasktrees.treeimpl; +import java.util.ArrayList; +import java.util.HashMap; + import de.ugoe.cs.autoquest.tasktrees.treeifc.ITask; import de.ugoe.cs.autoquest.tasktrees.treeifc.ITaskInfo; +import de.ugoe.cs.autoquest.tasktrees.treeifc.TaskMetric; /** @@ -41,11 +45,11 @@ */ private ITask task; - - /** - *- * the number of occurrences of this task - *
- */ - private int count; + + /** + *+ * all available measures for the task + *
+ */ + private ArrayList- * used to increase the counter of occurrences of this task by one - *
- */ - void increaseCount() { - count++; - } + * must be called to indicate that a new new measures for the provided metric are about to + * be calculated and added. + * + * + * @param metric the metric for which measures are about to be provided + */ + void addMeasure(TaskMetric metric) { + Measure measure = getMeasure(metric); + + if (measure != null) { + throw new IllegalArgumentException("measure for metric " + metric + " already exists."); + } + + measure = new Measure(metric); + measures.add(measure); + } + + /** + *+ * sets a specific value for a measure of a specific metric in the provided context of the task + *
+ * + * @param metric the metric to which the value belongs + * @param context the context of the task in which the measure was recorded + * @param value the value of the measure + */ + void setCount(TaskMetric metric, ITask context, int value) { + Measure measure = getMeasure(metric); + + if (measure == null) { + throw new IllegalArgumentException("unknown metric. Please create a measure " + + "for the metric before using it."); + } + + measure.set(context, value); + } + + /** + *+ * increases a specific value for a measure of a specific metric in the provided context of the + * task + *
+ * + * @param metric the metric to which the value belongs + * @param context the context of the task in which the measure was recorded + * @param increment the increment to be added to the value of the measure + */ + void increaseCount(TaskMetric metric, ITask context, int increment) { + Measure measure = getMeasure(metric); + + if (measure == null) { + throw new IllegalArgumentException("unknown metric. Please create a measure " + + "for the metric before using it."); + } + + measure.increase(context, increment); + } + + /** + *+ * convenience method to internally determine the measure for a specific metric + *
+ */ + private Measure getMeasure(TaskMetric metric) { + for (Measure candidate : measures) { + if (candidate.getMetric().equals(metric)) { + return candidate; + } + } + + return null; + } + + /** + *+ * implementation for the measure interface of the task info interface. Does nothing fancy + * except implementing the interface + *
+ * + * @author Patrick Harms + */ + private static class Measure implements IMeasure { + + /** + *+ * the metric to which the measure belongs + *
+ */ + private TaskMetric metric; + + /** + *+ * the observed values for the difference contexts of the task + *
+ */ + private HashMap+ * the context free value of the measure independent of the task context + *
+ */ + private int contextFreeValue = 0; + + /** + *+ * initializes the measure with a specific metric + *
+ */ + private Measure(TaskMetric metric) { + super(); + this.metric = metric; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.tasktrees.treeifc.ITaskInfo.IMeasure#getMetric() + */ + @Override + public TaskMetric getMetric() { + return metric; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.tasktrees.treeifc.ITaskInfo.IMeasure#getValue() + */ + @Override + public int getValue() { + return contextFreeValue; + } + + /* (non-Javadoc) + * @see de.ugoe.cs.autoquest.tasktrees.treeifc.ITaskInfo.IMeasure#getValue(de.ugoe.cs.autoquest.tasktrees.treeifc.ITask) + */ + @Override + public int getValue(ITask context) { + if ((context != null) && (values != null)) { + Integer currentValue = values.get(context); + + if (currentValue != null) { + return currentValue; + } + } + + return Integer.MIN_VALUE; + } + + /** + *+ * sets the value of the measure context free as well as specific to the provided context + *
+ */ + private void set(ITask context, int value) { + contextFreeValue = value; + + if (context != null) { + if (values == null) { + values = new HashMap+ * increases the value of the measure context free as well as specific to the provided + * context according to the provided increment + *
+ */ + private void increase(ITask context, int increment) { + contextFreeValue += increment; + + if (context != null) { + if (values == null) { + values = new HashMap* this is the default implementation of the interface {@link ITaskModel}. It - * does not do anything fancy except implementing the interface. + * does not do anything fancy except implementing the interface. It also calculates on + * initialisations the measures for diverse metrics of the task belonging to the model *
* @@ -44,4 +56,15 @@ */ private static final long serialVersionUID = 1L; + + /** + *+ * all metrics calculated by this type of task model + *
+ */ + private static final TaskMetric[] taskMetrics = new TaskMetric[] + { TaskMetric.COUNT, + TaskMetric.DEPTH, + TaskMetric.EVENT_COVERAGE, + TaskMetric.EVENT_COVERAGE_RATIO }; /** @@ -54,10 +77,9 @@ /** *- * the tasks contained in the user session belonging to the model as well as statistical infos - * about them - *
- */ - private Map
@@ -73,10 +95,4 @@
this.userSessions = userSessions;
-
- for (IUserSession session : this.userSessions) {
- for (ITaskInstance taskInstance : session) {
- addTasksToMap(taskInstance);
- }
- }
}
@@ -87,4 +103,5 @@
@Override
public List
- * internal convenience method to recursively add the tasks of a task instance and its
- * children to the task model
- *
- * internal convenience method to build the task model during initialization
- *
+ * internal convenience method that initializes the internal index and calculates all measures
+ * for metrics available for the tasks
+ *
+ * the index of task infos used internally. The index is created once and while that filled
+ * with task infos for each observed task containing all measures for metrics belonging
+ * to the tasks.
+ *
+ * the tasks contained in the user session belonging to the model as well as statistical
+ * infos about them
+ *
+ * called on initialization to fill the index with infos about the given task instance
+ * as well as to calculate the appropriate metrics
+ *
+ * internal convenience method to build the task model during initialization
+ *
+ * internal convenience method to build the task model during initialization. Adds a new
+ * task info object to the map for the provided task and fills it with measures. If there
+ * are already some task infos for the task, the contained measures are updated according
+ * to the parameters.
+ *
+ * internal convenience method to calculate the maximum depth of a task
+ *