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 ****
  /*
!  * Copyright (c) 1997, 2018, 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
--- 1,7 ----
  /*
!  * 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,108 ****
--- 99,118 ----
   * 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,453 ****
  
      // Bulk Operations
  
      /**
       * Returns {@code true} if this collection contains all of the elements
!      * in the specified collection.
       *
       * @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
--- 453,469 ----
  
      // Bulk Operations
  
      /**
       * Returns {@code true} if this collection contains all of the elements
!      * 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,502 ****
--- 507,524 ----
  
      /**
       * 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,562 ****
--- 573,590 ----
  
      /**
       * 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