- * This class is a data structure for holding symbols which is more efficient than a simple list. - * This data structure can be used with a comparator to adapt the effective list behavior and to - * define the equals strategy for comparing objects. After a certain size ({@link #MAX_LIST_SIZE}), - * the symbol map creates a symbol index consisting of buckets. This allows searching for symbols - * in a more efficient order as the search can start in the most appropriate of the internal - * buckets. + * This class is a data structure for holding task instances in form of a symbol map. It is more + * efficient than a simple list. This data structure can be used with a comparator to adapt the + * effective list behavior and to define the equals strategy for comparing task instances. After a + * certain size ({@link #MAX_LIST_SIZE}), the map creates an index consisting of buckets of similar + * task instances. This allows searching for task instances in a more efficient order as the search + * can start in the most appropriate of the internal buckets. *
*- * The class is called a map, although it is not. It may contain the same element as separate keys. - * This implementation is done for performance improvements. If it is required to really assure, - * that a key exists only once, then each call to the {@link #addSymbol(Object, Object)} method - * should be done only, if the {@link #containsSymbol(Object)} method for the same symbol returns - * false. + * The class is called a map, although it is not. It may contain the same task instances as + * separate keys. This implementation is done for performance improvements. If it is required to + * really assure, that a key exists only once, then each call to the + * {@link #addSymbol(Object, Object)} method should be done only, if the + * {@link #containsSymbol(Object)} method for the same symbol returns false. *
* @@ -68,6 +67,6 @@ /** *- * the maximum number of symbols in this map which is still only treated as list instead of - * using buckets. + * the maximum number of task instances in this map which is still only treated as list + * instead of using buckets. *
*/ @@ -76,6 +75,5 @@ /** *- * Comparator to be used for comparing the symbols with each other and to determine a bucket - * search order + * Comparator to be used for comparing the task instances with each other *
*/ @@ -84,5 +82,5 @@ /** *- * Internally maintained plain list of symbols and associated values + * Internally maintained plain list of task instances and associated values *
*/ @@ -91,5 +89,5 @@ /** *- * If the size of the map exceeds {@link #MAX_LIST_SIZE}, this is the symbol index using buckets + * If the size of the map exceeds {@link #MAX_LIST_SIZE}, this is the index using buckets * for optimizing the search order. *
@@ -99,7 +97,7 @@ /** *- * When using buckets, not any symbol may be associated a correct bucket by the used - * comparator. Therefore, we set a default bucket for all such symbols. This may change - * if the comparator defines the same bucket for a specific symbol. + * When using buckets, not any task instance may be associated a correct bucket. Therefore, we + * set a default bucket for all such task instances. This may change if the same bucket for a + * specific symbol is selected. *
*/ @@ -108,9 +106,8 @@ /** *- * Instantiates a symbol map with a comparator + * Instantiates a task instance map with a comparator *
* - * @param comparator the comparator to use for comparing symbols and for determining bucket - * search orders + * @param comparator the comparator to use for comparing task instances * * @throws IllegalArgumentException if the provided comparator is null @@ -127,5 +124,5 @@ /** *- * Copy constructure + * Copy constructor *
* @@ -149,5 +146,5 @@ /** *- * Returns the size of the map, i.e. the number of symbol entries + * Returns the size of the map, i.e. the number of task instance entries *
* @@ -171,12 +168,12 @@ /** *- * Returns true if the provided symbol was stored in this map. - *
- * - * @param symbol the symbol to check if it was stored in this map + * Returns true if the provided task instance was stored in this map. + * + * + * @param symbol the task instance to check if it was stored in this map * * @return as described * - * @throws IllegalArgumentException if the provided symbol is null + * @throws IllegalArgumentException if the provided task instance is null */ public boolean containsSymbol(ITaskInstance symbol) { @@ -190,14 +187,14 @@ /** *- * Returns the value associated to the provided symbol in this map. If there is no value - * associated to the given symbol or if the symbol is not stored in this map, the method - * returns null. - *
- * - * @param symbol the symbol to return the value for + * Returns the value associated to the provided task instance in this map. If there is no value + * associated to the given task instance or if the task instance is not stored in this map, + * the method returns null. + * + * + * @param symbol the task instance to return the value for * * @return as described * - * @throws IllegalArgumentException if the provided symbol is null + * @throws IllegalArgumentException if the provided task instance is null */ public V getValue(ITaskInstance symbol) { @@ -218,17 +215,18 @@ /** *- * Adds a symbol and an associated value to the map. If the value is null, the symbol is added, - * anyway and {@link #containsSymbol(Object)} will return true for that symbol. Adding the - * same symbol twice will produce two entries. This is contradictory to typical map - * implementations. To prevent this, the {@link #containsSymbol(Object)} and - * {@link #removeSymbol(Object)} methods should be used to ensure map behavior. - *
- * - * @param symbol the symbol to add to the map - * @param value the value to associate to the symbol in this map + * Adds a task instance and an associated value to the map. If the value is null, the task + * instance is added, anyway and {@link #containsSymbol(Object)} will return true for that + * task instance. Adding the same task instance twice will produce two entries. This is + * contradictory to typical map implementations. To prevent this, the + * {@link #containsSymbol(Object)} and {@link #removeSymbol(Object)} methods should be used to + * ensure map behavior. + * + * + * @param symbol the task instance to add to the map + * @param value the value to associate to the task instance in this map * * @return as described * - * @throws IllegalArgumentException if the provided symbol is null + * @throws IllegalArgumentException if the provided task instance is null */ public void addSymbol(ITaskInstance symbol, V value) { @@ -253,13 +251,13 @@ /** *- * Removes a symbol and its associated value from the map. If the symbol is stored several - * times, the first of its occurrences is removed. - *
- * - * @param symbol the symbol to be removed from the map + * Removes a task instance and its associated value from the map. If the task instance is + * stored several times, only the first of its occurrences is removed. + * + * + * @param symbol the task instance to be removed from the map * * @return as described * - * @throws IllegalArgumentException if the provided symbol is null + * @throws IllegalArgumentException if the provided task instance is null */ public V removeSymbol(ITaskInstance symbol) { @@ -286,5 +284,5 @@ /** *- * Returns a collection of all symbols in this map. + * Returns a collection of all task instances in this map. *
* @@ -297,7 +295,7 @@ /** *- * Returns a collection of all values associated to symbols in this map. May contain null - * values, if some of the symbols are mapped to null. The length of the returned collection - * is in any case the same as the size of the map. + * Returns a collection of all values associated to task instances in this map. May contain + * null values, if some of the task instances are mapped to null. The length of the returned + * collection is in any case the same as the size of the map. *
* @@ -310,5 +308,5 @@ /** *- * Removes all symbols and associated values from the map. + * Removes all task instances and associated values from the map. *
*/ @@ -348,6 +346,6 @@ /** *- * Internally used to create symbol buckets in case the number of stored symbols increased - * above {@link #MAX_LIST_SIZE}. + * Internally used to create task instance buckets in case the number of stored task instances + * increased above {@link #MAX_LIST_SIZE}. *
*/ @@ -363,9 +361,9 @@ /** *- * Adds a symbol and its value to its corresponding bucket. The corresponding bucket is - * retrieved from the symbol comparator. It is the first element of the search order returned - * by the symbol comparator. If the comparator does not define a search order for the symbol - * the entry is added to the default bucket. If the comparator defines a bucket id - * identical to the default bucket id, the default bucket id is shifted to another value. + * Adds a task instance and its value to its corresponding bucket. The corresponding bucket is + * the first element of the array returned by the method + * {@link #getBucketSearchOrder(ITaskInstance)}. If no search order for a task instance is + * defined, the entry is added to the default bucket. If the bucket id identical to the default + * bucket id, the default bucket id is shifted to another value. *
*/ @@ -393,16 +391,21 @@ /** - * - */ - public int[] getBucketSearchOrder(ITaskInstance taskInstance) { + *+ * returns the search order for a task instance which is different for event task instances, + * sequence instances, selection instances, and iteration instances + *
+ */ + private int[] getBucketSearchOrder(ITaskInstance taskInstance) { // 0 = sequence; 1 = selection; 2 = iteration; 3 = optional; 4 = event task in general; // other = hashCode of name of event type if (taskInstance instanceof IEventTaskInstance) { - // event tasks are most likely equal to those of the event type with the same name, - // Afterwards, they may be equal to iterations, optionals, other event tasks, + // event tasks are most likely equal to those of the same type happening on the same + // target. Afterwards, they should be equal to those of the event type with the same + // name. Afterwards, they may be equal to iterations, optionals, other event tasks, // selections, and finally the rest. - IEventType eventType = ((IEventTaskInstance) taskInstance).getEvent().getType(); - return new int[] { eventType.getName().hashCode(), 2, 3, 4, 1 }; + Event event = ((IEventTaskInstance) taskInstance).getEvent(); + return new int[] { event.getTarget().hashCode() + event.getType().getName().hashCode(), + event.getType().getName().hashCode(), 2, 3, 4, 1 }; } else if (taskInstance instanceof ISequenceInstance) { @@ -421,6 +424,6 @@ /** *- * Removes the entry for a given symbol from the buckets. It uses the bucket search order - * defined by the symbol comparator to find the symbol as fast as possible. + * Removes the entry for a given task instance from the buckets. It uses the bucket search order + * defined to find the task instance as fast as possible. *
*/ @@ -464,13 +467,14 @@ while (symbolBuckets.containsKey(defaultBucket)); - symbolBuckets.put(defaultBucket, symbolBuckets.get(oldDefaultBucket)); - } - - /** - *- * searches for the entry belonging to the given symbol. The method either uses the list if - * buckets are not used yet, or it uses the buckets and searches them in the order defined - * by the comparator. If the symbol isn't found and the comparator does not refer all buckets, - * then also the other buckets are searched for the symbol. + symbolBuckets.put(defaultBucket, symbolBuckets.remove(oldDefaultBucket)); + } + + /** + *
+ * searches for the entry belonging to the given task instance. The method either uses the + * list if buckets are not used yet, or it uses the buckets and searches them in the order + * defined by the method {@link #getBucketSearchOrder(ITaskInstance)}. If the task instances + * isn't found and the bucket search order does not refer all buckets, then also the other + * buckets are searched for the task instance. *
*/ @@ -529,5 +533,5 @@ /** *- * Internally used data structure for storing symbol value pairs + * Internally used data structure for storing task instance - value pairs *
* @@ -537,5 +541,5 @@ /** - * the symbol to map to a value + * the task instance to map to a value */ private ITaskInstance symbol; @@ -548,5 +552,6 @@ /** *- * Simple constructor for initializing the entry with a symbol and its associated value. + * Simple constructor for initializing the entry with a task instance and its associated + * value. *
*/ @@ -623,7 +628,7 @@ ** Used to create an efficient facade for accessing the internal list of entries either only - * for the symbols or only for the values. It is a default implementation of the collection - * interface. The entry facade provided to the constructor decides, if either the list - * accesses only the symbols or only the values. + * for the task instances or only for the values. It is a default implementation of the + * collection interface. The entry facade provided to the constructor decides, if either the + * list accesses only the task instances or only the values. *
* @@ -647,5 +652,6 @@ * */ - private ReadOnlyCollectionFacade(List- * Implementation of an iterator to facade an iterator on the internal list of symbol entries. + * Implementation of an iterator to facade an iterator on the internal list of task instance + * entries. *
* @@ -819,5 +826,5 @@ */ private ReadOnlyCollectionIteratorFacade(Iterator- * Used to facade symbol entries and to return only this part of an entry, that is relevant. + * Used to facade task instance entries and to return only this part of an entry, that is + * relevant. *
*