src/java.base/share/classes/java/util/Collection.java

rev 54827 : 6394757: AbstractSet.removeAll semantics are surprisingly dependent on relative sizes
Reviewed-by: XXX

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -99,10 +99,20 @@
  * unequal hash codes cannot be equal.)  More generally, implementations of
  * the various Collections Framework interfaces are free to take advantage of
  * the specified behavior of underlying {@link Object} methods wherever the
  * implementor deems it appropriate.
  *
+ * <p>Some collection interfaces and implementations may specify membership
+ * semantics that are not defined in terms of the {@code equals} method. For
+ * example, the {@link SortedSet#contains(Object) SortedSet.contains} method
+ * is defined in terms of a comparison method provided at construction time
+ * instead of the {@code equals} method. Such collections are well-defined,
+ * although their behavior may be counterintuitive when mixed with collections
+ * that use different membership semantics. For operations that may involve the
+ * membership semantics of more than one collection, it is specified which
+ * collection's membership semantics the operation uses.
+ *
  * <p>Some collection operations which perform recursive traversal of the
  * collection may fail with an exception for self-referential instances where
  * the collection directly or indirectly contains itself. This includes the
  * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
  * methods. Implementations may optionally handle the self-referential scenario,

@@ -443,11 +453,17 @@
 
     // Bulk Operations
 
     /**
      * Returns {@code true} if this collection contains all of the elements
-     * in the specified collection.
+     * in the specified collection. This operation uses the membership semantics
+     * of this collection.
+     *
+     * @implNote
+     * Most implementations will call this collection's {@code contains}
+     * method repeatedly. This may result in performance problems if the
+     * {@code contains} method has linear or worse performance.
      *
      * @param  c collection to be checked for containment in this collection
      * @return {@code true} if this collection contains all of the elements
      *         in the specified collection
      * @throws ClassCastException if the types of one or more elements

@@ -491,12 +507,18 @@
 
     /**
      * Removes all of this collection's elements that are also contained in the
      * specified collection (optional operation).  After this call returns,
      * this collection will contain no elements in common with the specified
+     * collection. This operation uses the membership semantics of the specified
      * collection.
      *
+     * @implNote
+     * Most implementations will call the specified collection's {@code contains}
+     * method repeatedly. This may result in performance problems if the specified
+     * collection's {@code contains} operation has linear or worse performance.
+     *
      * @param c collection containing elements to be removed from this collection
      * @return {@code true} if this collection changed as a result of the
      *         call
      * @throws UnsupportedOperationException if the {@code removeAll} method
      *         is not supported by this collection

@@ -551,12 +573,18 @@
 
     /**
      * Retains only the elements in this collection that are contained in the
      * specified collection (optional operation).  In other words, removes from
      * this collection all of its elements that are not contained in the
+     * specified collection. This operation uses the membership semantics of the
      * specified collection.
      *
+     * @implNote
+     * Most implementations will call the specified collection's {@code contains}
+     * method repeatedly. This may result in performance problems if the specified
+     * collection's {@code contains} operation has linear or worse performance.
+     *
      * @param c collection containing elements to be retained in this collection
      * @return {@code true} if this collection changed as a result of the call
      * @throws UnsupportedOperationException if the {@code retainAll} operation
      *         is not supported by this collection
      * @throws ClassCastException if the types of one or more elements