[COLLECTIONS-480] Narrow return type of BidiMap.values to Set. Thanks to Hollis Waite.

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

RELEASE-NOTES.txt

@@ -49,6 +49,7 @@ Changes since 4.0-alpha1
  - [COLLECTIONS-481] No collision detection/resolution was performed when calling "CompositeSet#addComposited(...)"
                      with more than one Set as argument. Also changed the the method with an array argument to use
                      a varargs parameter. Thanks to Hollis Waite.
+ - [COLLECTIONS-480] Narrow return type of "BidiMap#values()" to Set as the values are required to be unique. Thanks to Hollis Waite.
  - [COLLECTIONS-468] Renamed CompliantBag to CollectionBag.
  - [COLLECTIONS-475] Fixed conversion of timeout parameters in "PassiveExpiringMap".
 
@@ -150,6 +151,7 @@ New features
 Changed classes / methods
 -------------------------
 
+ o [COLLECTIONS-480] Narrow return type of "BidiMap#values()" to Set as the values are required to be unique. Thanks to Hollis Waite.
  o [COLLECTIONS-473] Made field "collection" in class "AbstractCollectionDecorator" private and added
                      setter "setCollection(Collection)" with scope protected to set the decorated collection
                      during de-serialization.

src/changes/changes.xml

@@ -27,6 +27,9 @@
      with more than one Set as argument. Also changed the the method with an array argument to use a
      varargs parameter.
     </action>
+    <action issue="COLLECTIONS-480" dev="tn" type="update" due-to="Hollis Waite">
+     Narrow return type of "BidiMap#values()" to Set as the values are required to be unique.
+    </action>
     <action issue="COLLECTIONS-475" dev="tn" type="fix">
      Fixed conversion of timeout parameters in "PassiveExpiringMap".
     </action>

src/main/java/org/apache/commons/collections4/BidiMap.java

@@ -16,6 +16,8 @@
  */
 package org.apache.commons.collections4;
 
+import java.util.Set;
+
 /**
  * Defines a map that allows bidirectional lookup between key and values.
  * <p>
@@ -124,4 +126,19 @@ public interface BidiMap<K, V> extends IterableMap<K, V> {
      */
     BidiMap<V, K> inverseBidiMap();
 
+    /**
+     * Returns a {@link Set} view of the values contained in this map.
+     * The set is backed by the map, so changes to the map are reflected
+     * in the set, and vice-versa.  If the map is modified while an iteration
+     * over the set is in progress (except through the iterator's own
+     * <tt>remove</tt> operation), the results of the iteration are undefined.
+     * The set supports element removal, which removes the corresponding
+     * mapping from the map, via the <tt>Iterator.remove</tt>,
+     * <tt>Collection.remove</tt>, <tt>removeAll</tt>,
+     * <tt>retainAll</tt> and <tt>clear</tt> operations.  It does not
+     * support the <tt>add</tt> or <tt>addAll</tt> operations.
+     *
+     * @return a set view of the values contained in this map
+     */
+    Set<V> values();
 }

src/main/java/org/apache/commons/collections4/bidimap/AbstractBidiMapDecorator.java

@@ -16,6 +16,8 @@
  */
 package org.apache.commons.collections4.bidimap;
 
+import java.util.Set;
+
 import org.apache.commons.collections4.BidiMap;
 import org.apache.commons.collections4.MapIterator;
 import org.apache.commons.collections4.map.AbstractMapDecorator;
@@ -76,4 +78,8 @@ public abstract class AbstractBidiMapDecorator<K, V>
         return decorated().inverseBidiMap();
     }
 
+    public Set<V> values() {
+        return decorated().values();
+    }
+
 }

src/main/java/org/apache/commons/collections4/bidimap/AbstractDualBidiMap.java

@@ -64,7 +64,7 @@ public abstract class AbstractDualBidiMap<K, V> implements BidiMap<K, V> {
     /**
      * View of the values.
      */
-    transient Collection<V> values = null;
+    transient Set<V> values = null;
 
     /**
      * View of the entries.
@@ -272,7 +272,7 @@ public abstract class AbstractDualBidiMap<K, V> implements BidiMap<K, V> {
      *
      * @return the values view
      */
-    public Collection<V> values() {
+    public Set<V> values() {
         if (values == null) {
             values = new Values<V>(this);
         }

src/main/java/org/apache/commons/collections4/bidimap/TreeBidiMap.java

@@ -21,7 +21,6 @@ import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;
 import java.util.AbstractSet;
-import java.util.Collection;
 import java.util.ConcurrentModificationException;
 import java.util.Iterator;
 import java.util.Map;
@@ -391,7 +390,7 @@ public class TreeBidiMap<K extends Comparable<K>, V extends Comparable<V>>
      *
      * @return a set view of the values contained in this map.
      */
-    public Collection<V> values() {
+    public Set<V> values() {
         if (valuesSet == null) {
             valuesSet = new ValueView(KEY);
         }
@@ -2128,7 +2127,7 @@ public class TreeBidiMap<K extends Comparable<K>, V extends Comparable<V>>
             return inverseKeySet;
         }
 
-        public Collection<K> values() {
+        public Set<K> values() {
             if (inverseValuesSet == null) {
                 inverseValuesSet = new KeyView(VALUE);
             }

src/main/java/org/apache/commons/collections4/bidimap/UnmodifiableBidiMap.java

@@ -16,7 +16,6 @@
  */
 package org.apache.commons.collections4.bidimap;
 
-import java.util.Collection;
 import java.util.Map;
 import java.util.Set;
 
@@ -24,7 +23,6 @@ import org.apache.commons.collections4.set.UnmodifiableSet;
 import org.apache.commons.collections4.BidiMap;
 import org.apache.commons.collections4.MapIterator;
 import org.apache.commons.collections4.Unmodifiable;
-import org.apache.commons.collections4.collection.UnmodifiableCollection;
 import org.apache.commons.collections4.iterators.UnmodifiableMapIterator;
 import org.apache.commons.collections4.map.UnmodifiableEntrySet;
 
@@ -106,9 +104,9 @@ public final class UnmodifiableBidiMap<K, V>
     }
 
     @Override
-    public Collection<V> values() {
+    public Set<V> values() {
-        final Collection<V> coll = super.values();
+        final Set<V> set = super.values();
-        return UnmodifiableCollection.unmodifiableCollection(coll);
+        return UnmodifiableSet.unmodifiableSet(set);
     }
 
     //-----------------------------------------------------------------------

src/main/java/org/apache/commons/collections4/bidimap/UnmodifiableOrderedBidiMap.java

@@ -16,7 +16,6 @@
  */
 package org.apache.commons.collections4.bidimap;
 
-import java.util.Collection;
 import java.util.Map;
 import java.util.Set;
 
@@ -24,7 +23,6 @@ import org.apache.commons.collections4.set.UnmodifiableSet;
 import org.apache.commons.collections4.OrderedBidiMap;
 import org.apache.commons.collections4.OrderedMapIterator;
 import org.apache.commons.collections4.Unmodifiable;
-import org.apache.commons.collections4.collection.UnmodifiableCollection;
 import org.apache.commons.collections4.iterators.UnmodifiableOrderedMapIterator;
 import org.apache.commons.collections4.map.UnmodifiableEntrySet;
 
@@ -106,9 +104,9 @@ public final class UnmodifiableOrderedBidiMap<K, V>
     }
 
     @Override
-    public Collection<V> values() {
+    public Set<V> values() {
-        final Collection<V> coll = super.values();
+        final Set<V> set = super.values();
-        return UnmodifiableCollection.unmodifiableCollection(coll);
+        return UnmodifiableSet.unmodifiableSet(set);
     }
 
     //-----------------------------------------------------------------------

src/main/java/org/apache/commons/collections4/bidimap/UnmodifiableSortedBidiMap.java

@@ -16,7 +16,6 @@
  */
 package org.apache.commons.collections4.bidimap;
 
-import java.util.Collection;
 import java.util.Map;
 import java.util.Set;
 import java.util.SortedMap;
@@ -25,7 +24,6 @@ import org.apache.commons.collections4.set.UnmodifiableSet;
 import org.apache.commons.collections4.OrderedMapIterator;
 import org.apache.commons.collections4.SortedBidiMap;
 import org.apache.commons.collections4.Unmodifiable;
-import org.apache.commons.collections4.collection.UnmodifiableCollection;
 import org.apache.commons.collections4.iterators.UnmodifiableOrderedMapIterator;
 import org.apache.commons.collections4.map.UnmodifiableEntrySet;
 import org.apache.commons.collections4.map.UnmodifiableSortedMap;
@@ -108,9 +106,9 @@ public final class UnmodifiableSortedBidiMap<K, V>
     }
 
     @Override
-    public Collection<V> values() {
+    public Set<V> values() {
-        final Collection<V> coll = super.values();
+        final Set<V> set = super.values();
-        return UnmodifiableCollection.unmodifiableCollection(coll);
+        return UnmodifiableSet.unmodifiableSet(set);
     }
 
     //-----------------------------------------------------------------------

src/site/xdoc/release_4_0.xml

@@ -151,6 +151,7 @@ This release is <b>not</b> source or binary compatible with v3.x.
 
 <center><h3>Changed classes / methods</h3></center>
 <ul>
+<li>Narrow return type of "BidiMap#values()" to Set as the values are required to be unique.</li>
 <li>Made field "collection" in class "AbstractCollectionDecorator" private and added setter "setCollection(Collection)" with scope protected to set the decorated collection during de-serialization.</li>
 <li>Replaced "Collection" with "Iterable" for method arguments where applicable.</li>
 <li>Changed "IteratorChain" to use internally a "Queue" instead of a "List". Iterators are removed from the queue once used and can be garbage collected after being exhausted. Additionally removed the methods "setIterator(Iterator)" and "getIterators()".</li>