Applying my patch for COLLECTIONS-256 - adding a decorateTransform method as used with Maps to all of the collection classes

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@572952 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/BagUtils.java

@@ -140,6 +140,9 @@ public class BagUtils {
      * Each object is passed through the transformer as it is added to the
      * Bag. It is important not to use the original bag after invoking this 
      * method, as it is a backdoor for adding untransformed objects.
+     * <p>
+     * Existing entries in the specified bag will not be transformed.
+     * If you want that behaviour, see {@link TransformedBag#decorateTransform}.
      *
      * @param bag  the bag to predicate, must not be null
      * @param transformer  the transformer for the bag, must not be null
@@ -231,6 +234,9 @@ public class BagUtils {
      * Each object is passed through the transformer as it is added to the
      * Bag. It is important not to use the original bag after invoking this 
      * method, as it is a backdoor for adding untransformed objects.
+     * <p>
+     * Existing entries in the specified bag will not be transformed.
+     * If you want that behaviour, see {@link TransformedSortedBag#decorateTransform}.
      *
      * @param bag  the bag to predicate, must not be null
      * @param transformer  the transformer for the bag, must not be null

src/java/org/apache/commons/collections/BufferUtils.java

@@ -188,6 +188,9 @@ public class BufferUtils {
      * Each object is passed through the transformer as it is added to the
      * Buffer. It is important not to use the original buffer after invoking this 
      * method, as it is a backdoor for adding untransformed objects.
+     * <p>
+     * Existing entries in the specified buffer will not be transformed.
+     * If you want that behaviour, see {@link TransformedBuffer#decorateTransform}.
      *
      * @param buffer  the buffer to predicate, must not be null
      * @param transformer  the transformer for the buffer, must not be null

src/java/org/apache/commons/collections/CollectionUtils.java

@@ -1201,6 +1201,9 @@ public class CollectionUtils {
      * Each object is passed through the transformer as it is added to the
      * Collection. It is important not to use the original collection after invoking this 
      * method, as it is a backdoor for adding untransformed objects.
+     * <p>
+     * Existing entries in the specified collection will not be transformed.
+     * If you want that behaviour, see {@link TransformedCollection#decorateTransform}.
      *
      * @param collection  the collection to predicate, must not be null
      * @param transformer  the transformer for the collection, must not be null

src/java/org/apache/commons/collections/ListUtils.java

@@ -350,6 +350,9 @@ public class ListUtils {
      * Each object is passed through the transformer as it is added to the
      * List. It is important not to use the original list after invoking this 
      * method, as it is a backdoor for adding untransformed objects.
+     * <p>
+     * Existing entries in the specified list will not be transformed.
+     * If you want that behaviour, see {@link TransformedList#decorateTransform}.
      *
      * @param list  the list to predicate, must not be null
      * @param transformer  the transformer for the list, must not be null

src/java/org/apache/commons/collections/SetUtils.java

@@ -212,6 +212,9 @@ public class SetUtils {
      * Each object is passed through the transformer as it is added to the
      * Set. It is important not to use the original set after invoking this 
      * method, as it is a backdoor for adding untransformed objects.
+     * <p>
+     * Existing entries in the specified set will not be transformed.
+     * If you want that behaviour, see {@link TransformedSet#decorateTransform}.
      *
      * @param set  the set to transform, must not be null
      * @param transformer  the transformer for the set, must not be null
@@ -313,6 +316,9 @@ public class SetUtils {
      * Each object is passed through the transformer as it is added to the
      * Set. It is important not to use the original set after invoking this 
      * method, as it is a backdoor for adding untransformed objects.
+     * <p>
+     * Existing entries in the specified set will not be transformed.
+     * If you want that behaviour, see {@link TransformedSortedSet#decorateTransform}.
      *
      * @param set  the set to transform, must not be null
      * @param transformer  the transformer for the set, must not be null

src/java/org/apache/commons/collections/bag/TransformedBag.java

@@ -17,6 +17,7 @@
 package org.apache.commons.collections.bag;
 
 import java.util.Set;
+import java.util.Collection;
 
 import org.apache.commons.collections.Bag;
 import org.apache.commons.collections.Transformer;
@@ -49,6 +50,7 @@ public class TransformedBag
      * <p>
      * If there are any elements already in the bag being decorated, they
      * are NOT transformed.
+     * Constrast this with {@link #decorateTransform}.
      * 
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -59,6 +61,32 @@ public class TransformedBag
         return new TransformedBag(bag, transformer);
     }
     
+    /**
+     * Factory method to create a transforming bag that will transform
+     * existing contents of the specified bag.
+     * <p>
+     * If there are any elements already in the bag being decorated, they
+     * will be transformed by this method.
+     * Constrast this with {@link #decorate}.
+     * 
+     * @param bag  the bag to decorate, must not be null
+     * @param transformer  the transformer to use for conversion, must not be null
+     * @return a new transformed Bag
+     * @throws IllegalArgumentException if bag or transformer is null
+     * @since Commons Collections 3.3
+     */
+    public static Bag decorateTransform(Bag bag, Transformer transformer) {
+        TransformedBag decorated = new TransformedBag(bag, transformer);
+        if (transformer != null && bag != null && bag.size() > 0) {
+            Object[] values = bag.toArray();
+            bag.clear();
+            for(int i=0; i<values.length; i++) {
+                decorated.getCollection().add(transformer.transform(values[i]));
+            }
+        }
+        return decorated;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).

src/java/org/apache/commons/collections/bag/TransformedSortedBag.java

@@ -47,6 +47,7 @@ public class TransformedSortedBag
      * <p>
      * If there are any elements already in the bag being decorated, they
      * are NOT transformed.
+     * Constrast this with {@link #decorateTransform}.
      * 
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -57,6 +58,32 @@ public class TransformedSortedBag
         return new TransformedSortedBag(bag, transformer);
     }
     
+    /**
+     * Factory method to create a transforming sorted bag that will transform
+     * existing contents of the specified sorted bag.
+     * <p>
+     * If there are any elements already in the bag being decorated, they
+     * will be transformed by this method.
+     * Constrast this with {@link #decorate}.
+     * 
+     * @param bag  the bag to decorate, must not be null
+     * @param transformer  the transformer to use for conversion, must not be null
+     * @return a new transformed SortedBag
+     * @throws IllegalArgumentException if bag or transformer is null
+     * @since Commons Collections 3.3
+     */
+    public static SortedBag decorateTransform(SortedBag bag, Transformer transformer) {
+        TransformedSortedBag decorated = new TransformedSortedBag(bag, transformer);
+        if (transformer != null && bag != null && bag.size() > 0) {
+            Object[] values = bag.toArray();
+            bag.clear();
+            for(int i=0; i<values.length; i++) {
+                decorated.getCollection().add(transformer.transform(values[i]));
+            }
+        }
+        return decorated;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).

src/java/org/apache/commons/collections/buffer/TransformedBuffer.java

@@ -45,6 +45,7 @@ public class TransformedBuffer extends TransformedCollection implements Buffer {
      * <p>
      * If there are any elements already in the buffer being decorated, they
      * are NOT transformed.
+     * Constrast this with {@link #decorateTransform}.
      * 
      * @param buffer  the buffer to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -55,6 +56,32 @@ public class TransformedBuffer extends TransformedCollection implements Buffer {
         return new TransformedBuffer(buffer, transformer);
     }
     
+    /**
+     * Factory method to create a transforming buffer that will transform
+     * existing contents of the specified buffer.
+     * <p>
+     * If there are any elements already in the buffer being decorated, they
+     * will be transformed by this method.
+     * Constrast this with {@link #decorate}.
+     * 
+     * @param buffer  the buffer to decorate, must not be null
+     * @param transformer  the transformer to use for conversion, must not be null
+     * @return a new transformed Buffer
+     * @throws IllegalArgumentException if buffer or transformer is null
+     * @since Commons Collections 3.3
+     */
+    public static Buffer decorateTransform(Buffer buffer, Transformer transformer) {
+        TransformedBuffer decorated = new TransformedBuffer(buffer, transformer);
+        if (transformer != null && buffer != null && buffer.size() > 0) {
+            Object[] values = buffer.toArray();
+            buffer.clear();
+            for(int i=0; i<values.length; i++) {
+                decorated.getCollection().add(transformer.transform(values[i]));
+            }
+        }
+        return decorated;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).

src/java/org/apache/commons/collections/collection/TransformedCollection.java

@@ -51,6 +51,7 @@ public class TransformedCollection extends AbstractSerializableCollectionDecorat
      * <p>
      * If there are any elements already in the collection being decorated, they
      * are NOT transformed.
+     * Constrast this with {@link #decorateTransform}.
      * 
      * @param coll  the collection to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -61,6 +62,32 @@ public class TransformedCollection extends AbstractSerializableCollectionDecorat
         return new TransformedCollection(coll, transformer);
     }
     
+    /**
+     * Factory method to create a transforming collection that will transform
+     * existing contents of the specified collection.
+     * <p>
+     * If there are any elements already in the collection being decorated, they
+     * will be transformed by this method.
+     * Constrast this with {@link #decorate}.
+     * 
+     * @param collection  the collection to decorate, must not be null
+     * @param transformer  the transformer to use for conversion, must not be null
+     * @return a new transformed Collection
+     * @throws IllegalArgumentException if collection or transformer is null
+     * @since Commons Collections 3.3
+     */
+    public static Collection decorateTransform(Collection collection, Transformer transformer) {
+        TransformedCollection decorated = new TransformedCollection(collection, transformer);
+        if (transformer != null && collection != null && collection.size() > 0) {
+            Object[] values = collection.toArray();
+            collection.clear();
+            for(int i=0; i<values.length; i++) {
+                decorated.getCollection().add(transformer.transform(values[i]));
+            }
+        }
+        return decorated;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).

src/java/org/apache/commons/collections/list/TransformedList.java

@@ -49,6 +49,7 @@ public class TransformedList extends TransformedCollection implements List {
      * <p>
      * If there are any elements already in the list being decorated, they
      * are NOT transformed.
+     * Constrast this with {@link #decorateTransform}.
      * 
      * @param list  the list to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -58,6 +59,32 @@ public class TransformedList extends TransformedCollection implements List {
         return new TransformedList(list, transformer);
     }
     
+    /**
+     * Factory method to create a transforming list that will transform
+     * existing contents of the specified list.
+     * <p>
+     * If there are any elements already in the list being decorated, they
+     * will be transformed by this method.
+     * Constrast this with {@link #decorate}.
+     * 
+     * @param list  the list to decorate, must not be null
+     * @param transformer  the transformer to use for conversion, must not be null
+     * @return a new transformed List
+     * @throws IllegalArgumentException if list or transformer is null
+     * @since Commons Collections 3.3
+     */
+    public static List decorateTransform(List list, Transformer transformer) {
+        TransformedList decorated = new TransformedList(list, transformer);
+        if (transformer != null && list != null && list.size() > 0) {
+            Object[] values = list.toArray();
+            list.clear();
+            for(int i=0; i<values.length; i++) {
+                decorated.getCollection().add(transformer.transform(values[i]));
+            }
+        }
+        return decorated;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).

src/java/org/apache/commons/collections/set/TransformedSet.java

@@ -46,6 +46,7 @@ public class TransformedSet extends TransformedCollection implements Set {
      * <p>
      * If there are any elements already in the set being decorated, they
      * are NOT transformed.
+     * Constrast this with {@link #decorateTransform}.
      * 
      * @param set  the set to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -55,6 +56,32 @@ public class TransformedSet extends TransformedCollection implements Set {
         return new TransformedSet(set, transformer);
     }
     
+    /**
+     * Factory method to create a transforming set that will transform
+     * existing contents of the specified set.
+     * <p>
+     * If there are any elements already in the set being decorated, they
+     * will be transformed by this method.
+     * Constrast this with {@link #decorate}.
+     * 
+     * @param set  the set to decorate, must not be null
+     * @param transformer  the transformer to use for conversion, must not be null
+     * @return a new transformed Set
+     * @throws IllegalArgumentException if set or transformer is null
+     * @since Commons Collections 3.3
+     */
+    public static Set decorateTransform(Set set, Transformer transformer) {
+        TransformedSet decorated = new TransformedSet(set, transformer);
+        if (transformer != null && set != null && set.size() > 0) {
+            Object[] values = set.toArray();
+            set.clear();
+            for(int i=0; i<values.length; i++) {
+                decorated.getCollection().add(transformer.transform(values[i]));
+            }
+        }
+        return decorated;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).

src/java/org/apache/commons/collections/set/TransformedSortedSet.java

@@ -46,6 +46,7 @@ public class TransformedSortedSet extends TransformedSet implements SortedSet {
      * <p>
      * If there are any elements already in the set being decorated, they
      * are NOT transformed.
+     * Constrast this with {@link #decorateTransform}.
      * 
      * @param set  the set to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -55,6 +56,32 @@ public class TransformedSortedSet extends TransformedSet implements SortedSet {
         return new TransformedSortedSet(set, transformer);
     }
     
+    /**
+     * Factory method to create a transforming sorted set that will transform
+     * existing contents of the specified sorted set.
+     * <p>
+     * If there are any elements already in the set being decorated, they
+     * will be transformed by this method.
+     * Constrast this with {@link #decorate}.
+     * 
+     * @param set  the set to decorate, must not be null
+     * @param transformer  the transformer to use for conversion, must not be null
+     * @return a new transformed SortedSet
+     * @throws IllegalArgumentException if set or transformer is null
+     * @since Commons Collections 3.3
+     */
+    public static SortedSet decorateTransform(SortedSet set, Transformer transformer) {
+        TransformedSortedSet decorated = new TransformedSortedSet(set, transformer);
+        if (transformer != null && set != null && set.size() > 0) {
+            Object[] values = set.toArray();
+            set.clear();
+            for(int i=0; i<values.length; i++) {
+                decorated.getCollection().add(transformer.transform(values[i]));
+            }
+        }
+        return decorated;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).

src/test/org/apache/commons/collections/bag/TestTransformedBag.java

@@ -63,7 +63,23 @@ public class TestTransformedBag extends AbstractTestBag {
         
         assertEquals(false, bag.remove(els[0]));
         assertEquals(true, bag.remove(new Integer((String) els[0])));
+    }
 
+    public void testTransformedBag_decorateTransform() {
+        Bag originalBag = new HashBag();
+        Object[] els = new Object[] {"1", "3", "5", "7", "2", "4", "6"};
+        for (int i = 0; i < els.length; i++) {
+            originalBag.add(els[i]);
+        }
+        Bag bag = TransformedBag.decorateTransform(originalBag, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        assertEquals(els.length, bag.size());
+        for (int i = 0; i < els.length; i++) {
+            assertEquals(true, bag.contains(new Integer((String) els[i])));
+            assertEquals(false, bag.contains(els[i]));
+        }
+        
+        assertEquals(false, bag.remove(els[0]));
+        assertEquals(true, bag.remove(new Integer((String) els[0])));
     }
 
     public String getCompatibilityVersion() {

src/test/org/apache/commons/collections/bag/TestTransformedSortedBag.java

@@ -64,6 +64,21 @@ public class TestTransformedSortedBag extends AbstractTestSortedBag {
         
     }
 
+    public void testTransformedBag_decorateTransform() {
+        Bag originalBag = new TreeBag();
+        Object[] els = new Object[] {"1", "3", "5", "7", "2", "4", "6"};
+        for (int i = 0; i < els.length; i++) {
+            originalBag.add(els[i]);
+        }
+        Bag bag = TransformedBag.decorateTransform(originalBag, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        assertEquals(els.length, bag.size());
+        for (int i = 0; i < els.length; i++) {
+            assertEquals(true, bag.contains(new Integer((String) els[i])));
+        }
+        
+        assertEquals(true, bag.remove(new Integer((String) els[0])));
+    }
+
     public String getCompatibilityVersion() {
         return "3.1";
     }

src/test/org/apache/commons/collections/buffer/TestTransformedBuffer.java

@@ -63,4 +63,25 @@ public class TestTransformedBuffer extends TestCase {
         assertEquals(true, buffer.remove(new Integer((String) els[0])));
         
     }
+
+    public void testTransformedBuffer_decorateTransform() {
+        Buffer originalBuffer = new ArrayStack();
+        Object[] els = new Object[] {"1", "3", "5", "7", "2", "4", "6"};
+        for (int i = 0; i < els.length; i++) {
+            originalBuffer.add(els[i]);
+        }
+        Buffer buffer = TransformedBuffer.decorateTransform(originalBuffer, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        assertEquals(els.length, buffer.size());
+        for (int i = 0; i < els.length; i++) {
+            assertEquals(true, buffer.contains(new Integer((String) els[i])));
+            assertEquals(false, buffer.contains(els[i]));
+        }
+        
+        assertEquals(false, buffer.remove(els[0]));
+        assertEquals(true, buffer.remove(new Integer((String) els[0])));
+    }
+
+    public String getCompatibilityVersion() {
+        return "3.1";
+    }
 }

src/test/org/apache/commons/collections/collection/TestTransformedCollection.java

@@ -105,6 +105,23 @@ public class TestTransformedCollection extends AbstractTestCollection {
         assertEquals(true, coll.remove(new Integer((String) els[0])));
     }
 
+    public void testTransformedCollection_decorateTransform() {
+        Collection originalCollection = new ArrayList();
+        Object[] els = getFullElements();
+        for (int i = 0; i < els.length; i++) {
+            originalCollection.add(els[i]);
+        }
+        Collection collection = TransformedCollection.decorateTransform(originalCollection, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        assertEquals(els.length, collection.size());
+        for (int i = 0; i < els.length; i++) {
+            assertEquals(true, collection.contains(new Integer((String) els[i])));
+            assertEquals(false, collection.contains(els[i]));
+        }
+        
+        assertEquals(false, collection.remove(els[0]));
+        assertEquals(true, collection.remove(new Integer((String) els[0])));
+    }
+
     public String getCompatibilityVersion() {
         return "3.1";
     }

src/test/org/apache/commons/collections/list/TestTransformedList.java

@@ -118,6 +118,23 @@ public class TestTransformedList extends AbstractTestList {
         assertEquals(new Integer(2), list.get(2));
     }
 
+    public void testTransformedList_decorateTransform() {
+        List originalList = new ArrayList();
+        Object[] els = new Object[] {"1", "3", "5", "7", "2", "4", "6"};
+        for (int i = 0; i < els.length; i++) {
+            originalList.add(els[i]);
+        }
+        List list = TransformedList.decorateTransform(originalList, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        assertEquals(els.length, list.size());
+        for (int i = 0; i < els.length; i++) {
+            assertEquals(true, list.contains(new Integer((String) els[i])));
+            assertEquals(false, list.contains(els[i]));
+        }
+        
+        assertEquals(false, list.remove(els[0]));
+        assertEquals(true, list.remove(new Integer((String) els[0])));
+    }
+
     public String getCompatibilityVersion() {
         return "3.1";
     }

src/test/org/apache/commons/collections/set/TestTransformedSet.java

@@ -86,6 +86,23 @@ public class TestTransformedSet extends AbstractTestSet {
         
     }
 
+    public void testTransformedSet_decorateTransform() {
+        Set originalSet = new HashSet();
+        Object[] els = new Object[] {"1", "3", "5", "7", "2", "4", "6"};
+        for (int i = 0; i < els.length; i++) {
+            originalSet.add(els[i]);
+        }
+        Set set = TransformedSet.decorateTransform(originalSet, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        assertEquals(els.length, set.size());
+        for (int i = 0; i < els.length; i++) {
+            assertEquals(true, set.contains(new Integer((String) els[i])));
+            assertEquals(false, set.contains(els[i]));
+        }
+        
+        assertEquals(false, set.remove(els[0]));
+        assertEquals(true, set.remove(new Integer((String) els[0])));
+    }
+
     public String getCompatibilityVersion() {
         return "3.1";
     }

src/test/org/apache/commons/collections/set/TestTransformedSortedSet.java

@@ -17,10 +17,9 @@
 package org.apache.commons.collections.set;
 
 import java.util.Arrays;
-import java.util.HashSet;
+import java.util.TreeSet;
 import java.util.Set;
 import java.util.SortedSet;
-import java.util.TreeSet;
 
 import junit.framework.Test;
 
@@ -64,21 +63,34 @@ public class TestTransformedSortedSet extends AbstractTestSortedSet {
     
     //-----------------------------------------------------------------------   
     public void testTransformedSet() {
-        Set set = TransformedSortedSet.decorate(new HashSet(), TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        Set set = TransformedSortedSet.decorate(new TreeSet(), TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
         assertEquals(0, set.size());
         Object[] els = new Object[] {"1", "3", "5", "7", "2", "4", "6"};
         for (int i = 0; i < els.length; i++) {
             set.add(els[i]);
             assertEquals(i + 1, set.size());
             assertEquals(true, set.contains(new Integer((String) els[i])));
-            assertEquals(false, set.contains(els[i]));
         }
         
-        assertEquals(false, set.remove(els[0]));
         assertEquals(true, set.remove(new Integer((String) els[0])));
         
     } 
 
+    public void testTransformedSet_decorateTransform() {
+        Set originalSet = new TreeSet();
+        Object[] els = new Object[] {"1", "3", "5", "7", "2", "4", "6"};
+        for (int i = 0; i < els.length; i++) {
+            originalSet.add(els[i]);
+        }
+        Set set = TransformedSortedSet.decorateTransform(originalSet, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER);
+        assertEquals(els.length, set.size());
+        for (int i = 0; i < els.length; i++) {
+            assertEquals(true, set.contains(new Integer((String) els[i])));
+        }
+        
+        assertEquals(true, set.remove(new Integer((String) els[0])));
+    }
+
     public String getCompatibilityVersion() {
         return "3.1";
     }