de.scrum_master.util

Class UpdateableTreeSet<E extends UpdateableTreeSet.Updateable>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractSet<E>

java.util.TreeSet<E>

de.scrum_master.util.UpdateableTreeSet<E>

All Implemented Interfaces:

Serializable, Cloneable, Iterable<E>, Collection<E>, NavigableSet<E>, Set<E>, SortedSet<E>

public class UpdateableTreeSet<E extends UpdateableTreeSet.Updateable>
extends TreeSet<E>

This class is just a thin layer around its parent class, adding an element updating and re-sorting feature which works as follows:

As you might know you should never add or remove elements of Java collections while iterating over them in a loop. There is one exception: If you use an Iterator you may safely use its remove method. Many people do not know that or are even unaware of that method's existence because they iterate using for loops.

Another problem specifically with sorted collections is that even if they are Comparable or use an explicit Comparator, their elements will be sorted at insertion time only and the sort order not updated even if their sorting keys change. If you want to achieve a refresh, you have to

1. remove them from the collection,
2. update their values and then
3. add them back again.

This class does just that, but in a structured fashion as a bulk operation after your loop has finished or as a single-element operation if you want to do it outside a loop.

Usage example:

 import de.scrum_master.util.UpdateableTreeSet;
 import de.scrum_master.util.UpdateableTreeSet.Updateable;

 class MyType implements Updateable {
     void update(Object newValue) {
         // Change the receiver's value
     }
 }

 SortedSet mySortedSet = new UpdateableTreeSet();

 // Add elements to mySortedSet...

 for (MyType element : mySortedSet) {
     if (removeCondition)
         markForRemoval(element);
     if (updateCondition)
         markForUpdate(element, newValue);
 }

 mySortedSet.updateMarked();
 

Special thanks go to user tucuxi at stackoverflow.com because his answer in one of the discussion threads inspired me to implement this class based on his idea. My version is just a bit more sophisticated because it supports deferred updates and is thus useful within for loops.

Author:

Alexander Kriegisch, Scrum-Master.de

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	UpdateableTreeSet.Updateable UpdateableTreeSet elements must implement this interface in order to provide a structured way of updating themselves at the right moment during an update operation, i.e.

Constructor Summary

Constructors

Constructor and Description
UpdateableTreeSet()
UpdateableTreeSet(Collection<? extends E> c)
UpdateableTreeSet(Comparator<? super E> comparator)
UpdateableTreeSet(SortedSet<E> s)

Method Summary

Methods

Modifier and Type	Method and Description
void	markForRemoval(E element) Mark an element for subsequent removal by updateMarked().
void	markForUpdate(E element) Convenience method passing a null value to markForUpdate(Updateable, Object)
void	markForUpdate(E element, Object newValue) Mark an element for subsequent update by updateMarked().
boolean	update(E element) Convenience method passing a null value to update(Updateable, Object)
boolean	update(E element, Object newValue) Performs an immediate update on a single element so as to trigger its re-ordering within the collection.
void	updateAll() Updates the total sort order of the set by removing and re-adding all elements.
void	updateMarked() Performs a bulk removal on all elements previously marked for removal, a bulk update on all elements previously marked for update so as to trigger their re-sorting within the collection.

Methods inherited from class java.util.TreeSet

add, addAll, ceiling, clear, clone, comparator, contains, descendingIterator, descendingSet, first, floor, headSet, headSet, higher, isEmpty, iterator, last, lower, pollFirst, pollLast, remove, size, subSet, subSet, tailSet, tailSet

Methods inherited from class java.util.AbstractSet

equals, hashCode, removeAll

Methods inherited from class java.util.AbstractCollection

containsAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

containsAll, equals, hashCode, removeAll, retainAll, toArray, toArray

Constructor Detail

UpdateableTreeSet

public UpdateableTreeSet()

UpdateableTreeSet

public UpdateableTreeSet(Collection<? extends E> c)

UpdateableTreeSet

public UpdateableTreeSet(Comparator<? super E> comparator)

UpdateableTreeSet

public UpdateableTreeSet(SortedSet<E> s)

Method Detail

markForUpdate

public void markForUpdate(E element,
                 Object newValue)

Mark an element for subsequent update by updateMarked().

Attention: Beware of manually modifying a marked element before its scheduled update. It might not be found anymore (and thus not removed) because of its changed key, which later could lead to strange double entries in the collection.

markForUpdate

public void markForUpdate(E element)

Convenience method passing a null value to markForUpdate(Updateable, Object)

markForRemoval

public void markForRemoval(E element)

Mark an element for subsequent removal by updateMarked().

Attention: Beware of manually modifying a marked element before its scheduled removal. It might not be found anymore (and thus not removed) because of its changed key, which later could lead to strange double entries in the collection.

updateMarked

public void updateMarked()

Performs

1. a bulk removal on all elements previously marked for removal,
2. a bulk update on all elements previously marked for update so as to trigger their re-sorting within the collection.

The marks will be removed from the processed elements after the bulk operation, so you can start to mark other elements afterwards.

Please note that if any remove or update action fails, this will be silently ignored as long as there are no exceptions.

Attention: Do not call this method while looping over the collection and beware of manually modifying any marked elements before their scheduled update/removal. They might not be found anymore (and thus not removed) because of their changed keys, which later could lead to strange double entries in the collection.

updateAll

public void updateAll()

Updates the total sort order of the set by removing and re-adding all elements.

You may use this method in situations when properties of elements within the set have been mofified, which usually should be avoided. This method refreshes and in a way "repairs" the set, because if you modify elements within the set, their fixed sort order might contradict their actual state, which might disturb iterators and operations like TreeSet.contains(java.lang.Object) or TreeSet.remove(java.lang.Object).

Attention: All previously recorded update/removal marks will be reset before the update, so do not expect any elements to be removed by this operation.

update

public boolean update(E element,
             Object newValue)

Performs an immediate update on a single element so as to trigger its re-ordering within the collection. Calling this method has no effect on the list of elements marked for removal or update.

Attention: Do not call this method while looping over the collection.

Parameters:

element - the element to be updated

newValue - element's new value (if any)

Returns:

true if element was found in collection and updated (i.e. removed and added back) successfully

update

public boolean update(E element)

Convenience method passing a null value to update(Updateable, Object)