diff --git a/RELEASE-NOTES.html b/RELEASE-NOTES.html index 25d135f10..2bcd83474 100644 --- a/RELEASE-NOTES.html +++ b/RELEASE-NOTES.html @@ -68,6 +68,7 @@ If this causes major headaches to anyone please contact commons-dev at jakarta.a
  • CollectionUtils/ListUtils - retainAll/removeAll that don't change original colllection
  • BlockingBuffer - now includes stack trace if InterupttedException occurs [33700]
  • BlockingBuffer - new methods that allow get and remove with a timeout [27691]
    • +
  • Transformed*Map - new factory decorateTransform() that transforms any existing entries in the map [30959]

    • BUG FIXES

    @@ -98,6 +99,7 @@ If this causes major headaches to anyone please contact commons-dev at jakarta.a

    JAVADOC

    diff --git a/src/java/org/apache/commons/collections/MapUtils.java b/src/java/org/apache/commons/collections/MapUtils.java index d364027ac..512429302 100644 --- a/src/java/org/apache/commons/collections/MapUtils.java +++ b/src/java/org/apache/commons/collections/MapUtils.java @@ -1264,11 +1264,19 @@ public class MapUtils { /** * Returns a transformed map backed by the given map. *

    + * This method returns a new map (decorating the specified map) that + * will transform any new entries added to it. + * Existing entries in the specified map will not be transformed. + * If you want that behaviour, see {@link TransformedMap#decorateTransform}. + *

    * Each object is passed through the transformers as it is added to the * Map. It is important not to use the original map after invoking this * method, as it is a backdoor for adding untransformed objects. + *

    + * If there are any elements already in the map being decorated, they + * are NOT transformed. * - * @param map the map to transform, must not be null + * @param map the map to transform, must not be null, typically empty * @param keyTransformer the transformer for the map keys, null means no transformation * @param valueTransformer the transformer for the map values, null means no transformation * @return a transformed map backed by the given map @@ -1499,11 +1507,19 @@ public class MapUtils { /** * Returns a transformed sorted map backed by the given map. *

    + * This method returns a new sorted map (decorating the specified map) that + * will transform any new entries added to it. + * Existing entries in the specified map will not be transformed. + * If you want that behaviour, see {@link TransformedSortedMap#decorateTransform}. + *

    * Each object is passed through the transformers as it is added to the * Map. It is important not to use the original map after invoking this * method, as it is a backdoor for adding untransformed objects. + *

    + * If there are any elements already in the map being decorated, they + * are NOT transformed. * - * @param map the map to transform, must not be null + * @param map the map to transform, must not be null, typically empty * @param keyTransformer the transformer for the map keys, null means no transformation * @param valueTransformer the transformer for the map values, null means no transformation * @return a transformed map backed by the given map diff --git a/src/java/org/apache/commons/collections/map/TransformedMap.java b/src/java/org/apache/commons/collections/map/TransformedMap.java index 36ef470f3..eaa999902 100644 --- a/src/java/org/apache/commons/collections/map/TransformedMap.java +++ b/src/java/org/apache/commons/collections/map/TransformedMap.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2005 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -56,16 +56,40 @@ public class TransformedMap *

    * If there are any elements already in the map being decorated, they * are NOT transformed. + * Constrast this with {@link #decorateTransform}. * * @param map the map to decorate, must not be null - * @param keyTransformer the transformer to use for key conversion, null means no conversion - * @param valueTransformer the transformer to use for value conversion, null means no conversion + * @param keyTransformer the transformer to use for key conversion, null means no transformation + * @param valueTransformer the transformer to use for value conversion, null means no transformation * @throws IllegalArgumentException if map is null */ public static Map decorate(Map map, Transformer keyTransformer, Transformer valueTransformer) { return new TransformedMap(map, keyTransformer, valueTransformer); } + /** + * Factory method to create a transforming map that will transform + * existing contents of the specified map. + *

    + * If there are any elements already in the map being decorated, they + * will be transformed by this method. + * Constrast this with {@link #decorate}. + * + * @param map the map to decorate, must not be null + * @param keyTransformer the transformer to use for key conversion, null means no transformation + * @param valueTransformer the transformer to use for value conversion, null means no transformation + * @throws IllegalArgumentException if map is null + */ + public static Map decorateTransform(Map map, Transformer keyTransformer, Transformer valueTransformer) { + TransformedMap decorated = new TransformedMap(map, keyTransformer, valueTransformer); + if (map.size() > 0) { + Map transformed = decorated.transformMap(map); + decorated.clear(); + decorated.getMap().putAll(transformed); // avoids double transformation + } + return decorated; + } + //----------------------------------------------------------------------- /** * Constructor that wraps (not copies). diff --git a/src/java/org/apache/commons/collections/map/TransformedSortedMap.java b/src/java/org/apache/commons/collections/map/TransformedSortedMap.java index 00ee57c10..01121ee58 100644 --- a/src/java/org/apache/commons/collections/map/TransformedSortedMap.java +++ b/src/java/org/apache/commons/collections/map/TransformedSortedMap.java @@ -1,5 +1,5 @@ /* - * Copyright 2003-2004 The Apache Software Foundation + * Copyright 2003-2005 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,6 +16,7 @@ package org.apache.commons.collections.map; import java.util.Comparator; +import java.util.Map; import java.util.SortedMap; import org.apache.commons.collections.Transformer; @@ -47,6 +48,7 @@ public class TransformedSortedMap *

    * If there are any elements already in the map being decorated, they * are NOT transformed. + * Constrast this with {@link #decorateTransform}. * * @param map the map to decorate, must not be null * @param keyTransformer the predicate to validate the keys, null means no transformation @@ -57,6 +59,29 @@ public class TransformedSortedMap return new TransformedSortedMap(map, keyTransformer, valueTransformer); } + /** + * Factory method to create a transforming sorted map that will transform + * existing contents of the specified map. + *

    + * If there are any elements already in the map being decorated, they + * will be transformed by this method. + * Constrast this with {@link #decorate}. + * + * @param map the map to decorate, must not be null + * @param keyTransformer the transformer to use for key conversion, null means no transformation + * @param valueTransformer the transformer to use for value conversion, null means no transformation + * @throws IllegalArgumentException if map is null + */ + public static SortedMap decorateTransform(SortedMap map, Transformer keyTransformer, Transformer valueTransformer) { + TransformedSortedMap decorated = new TransformedSortedMap(map, keyTransformer, valueTransformer); + if (map.size() > 0) { + Map transformed = decorated.transformMap(map); + decorated.clear(); + decorated.getMap().putAll(transformed); // avoids double transformation + } + return decorated; + } + //----------------------------------------------------------------------- /** * Constructor that wraps (not copies). diff --git a/src/test/org/apache/commons/collections/map/TestTransformedMap.java b/src/test/org/apache/commons/collections/map/TestTransformedMap.java index c6544fe14..666134953 100644 --- a/src/test/org/apache/commons/collections/map/TestTransformedMap.java +++ b/src/test/org/apache/commons/collections/map/TestTransformedMap.java @@ -97,6 +97,38 @@ public class TestTransformedMap extends AbstractTestMap { assertEquals(new Integer(88), map.get(entry.getKey())); } + //----------------------------------------------------------------------- + public void testFactory_Decorate() { + Map base = new HashMap(); + base.put("A", "1"); + base.put("B", "2"); + base.put("C", "3"); + + Map trans = TransformedMap.decorate(base, null, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER); + assertEquals(3, trans.size()); + assertEquals("1", trans.get("A")); + assertEquals("2", trans.get("B")); + assertEquals("3", trans.get("C")); + trans.put("D", "4"); + assertEquals(new Integer(4), trans.get("D")); + } + + public void testFactory_decorateTransform() { + Map base = new HashMap(); + base.put("A", "1"); + base.put("B", "2"); + base.put("C", "3"); + + Map trans = TransformedMap.decorateTransform(base, null, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER); + assertEquals(3, trans.size()); + assertEquals(new Integer(1), trans.get("A")); + assertEquals(new Integer(2), trans.get("B")); + assertEquals(new Integer(3), trans.get("C")); + trans.put("D", "4"); + assertEquals(new Integer(4), trans.get("D")); + } + + //----------------------------------------------------------------------- public String getCompatibilityVersion() { return "3.1"; } diff --git a/src/test/org/apache/commons/collections/map/TestTransformedSortedMap.java b/src/test/org/apache/commons/collections/map/TestTransformedSortedMap.java index 2157b8e14..1fc3fd7ad 100644 --- a/src/test/org/apache/commons/collections/map/TestTransformedSortedMap.java +++ b/src/test/org/apache/commons/collections/map/TestTransformedSortedMap.java @@ -17,6 +17,7 @@ package org.apache.commons.collections.map; import java.util.Map; import java.util.Set; +import java.util.SortedMap; import java.util.TreeMap; import junit.framework.Test; @@ -108,6 +109,38 @@ public class TestTransformedSortedMap extends AbstractTestSortedMap { assertEquals(new Integer(88), map.get(entry.getKey())); } + //----------------------------------------------------------------------- + public void testFactory_Decorate() { + SortedMap base = new TreeMap(); + base.put("A", "1"); + base.put("B", "2"); + base.put("C", "3"); + + SortedMap trans = TransformedSortedMap.decorate(base, null, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER); + assertEquals(3, trans.size()); + assertEquals("1", trans.get("A")); + assertEquals("2", trans.get("B")); + assertEquals("3", trans.get("C")); + trans.put("D", "4"); + assertEquals(new Integer(4), trans.get("D")); + } + + public void testFactory_decorateTransform() { + SortedMap base = new TreeMap(); + base.put("A", "1"); + base.put("B", "2"); + base.put("C", "3"); + + SortedMap trans = TransformedSortedMap.decorateTransform(base, null, TestTransformedCollection.STRING_TO_INTEGER_TRANSFORMER); + assertEquals(3, trans.size()); + assertEquals(new Integer(1), trans.get("A")); + assertEquals(new Integer(2), trans.get("B")); + assertEquals(new Integer(3), trans.get("C")); + trans.put("D", "4"); + assertEquals(new Integer(4), trans.get("D")); + } + + //----------------------------------------------------------------------- public String getCompatibilityVersion() { return "3.1"; }