Note that this implementation will throw an * {@code UnsupportedOperationException} if the iterator returned by the @@ -369,6 +373,9 @@ * and this collection contains one or more elements in common with the * specified collection. * + * @implNote + * {@inheritDoc} + * * @throws UnsupportedOperationException {@inheritDoc} * @throws ClassCastException {@inheritDoc} * @throws NullPointerException {@inheritDoc} @@ -393,10 +400,11 @@ * {@inheritDoc} * * @implSpec - * This implementation iterates over this collection, checking each - * element returned by the iterator in turn to see if it's contained - * in the specified collection. If it's not so contained, it's removed - * from this collection with the iterator's {@code remove} method. + * This implementation iterates over each element of this collection by + * obtaining an iterator from the {@code iterator} method. Each element + * is passed to the {@code contains} method of the specified collection. + * If {@code contains} returns {@code false}, the element is removed from + * this collection with the iterator's {@code remove} method. * *
Note that this implementation will throw an * {@code UnsupportedOperationException} if the iterator returned by the @@ -404,6 +412,9 @@ * and this collection contains one or more elements not present in the * specified collection. * + * @implNote + * {@inheritDoc} + * * @throws UnsupportedOperationException {@inheritDoc} * @throws ClassCastException {@inheritDoc} * @throws NullPointerException {@inheritDoc} --- old/src/java.base/share/classes/java/util/AbstractList.java 2019-05-13 17:16:08.000000000 -0700 +++ new/src/java.base/share/classes/java/util/AbstractList.java 2019-05-13 17:16:07.000000000 -0700 @@ -1,5 +1,5 @@ /* - * 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 @@ -512,6 +512,8 @@ // Comparison and hashing + // FIXME: the first paragraph below is copied from Set.equals, because + // {@inheritDoc} inherits text from superclasses, not interfaces (see JDK-6376959). /** * Compares the specified object with this list for equality. Returns * {@code true} if and only if the specified object is also a list, both @@ -519,7 +521,9 @@ * the two lists are equal. (Two elements {@code e1} and * {@code e2} are equal if {@code (e1==null ? e2==null : * e1.equals(e2))}.) In other words, two lists are defined to be - * equal if they contain the same elements in the same order. + * equal if they contain the same elements in the same order. This + * definition ensures that the {@code equals} method works properly across + * different implementations of the {@code List} interface. * * @implSpec * This implementation first checks if the specified object is this --- old/src/java.base/share/classes/java/util/AbstractSet.java 2019-05-13 17:16:09.000000000 -0700 +++ new/src/java.base/share/classes/java/util/AbstractSet.java 2019-05-13 17:16:09.000000000 -0700 @@ -1,5 +1,5 @@ /* - * 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 @@ -65,20 +65,27 @@ // Comparison and hashing + // FIXME: the first paragraph below is copied from Set.equals, because + // {@inheritDoc} inherits text from superclasses, not interfaces (see JDK-6376959). /** - * Compares the specified object with this set for equality. Returns - * {@code true} if the given object is also a set, the two sets have - * the same size, and every member of the given set is contained in - * this set. This ensures that the {@code equals} method works - * properly across different implementations of the {@code Set} - * interface.
+ * Compares the specified object with this set for equality. Returns + * {@code true} if the specified object is also a set, the two sets + * have the same size, and every member of the specified set is + * contained in this set. This operation uses the membership semantics + * of this set. This definition ensures that the {@code equals} method + * works properly across different implementations of the + * {@code Set} interface. * + * @implSpec * This implementation first checks if the specified object is this * set; if so it returns {@code true}. Then, it checks if the * specified object is a set whose size is identical to the size of - * this set; if not, it returns false. If so, it returns + * this set; if not, it returns {@code false}. If so, it returns * {@code containsAll((Collection) o)}. * + * @implNote + * {@inheritDoc} + * * @param o object to be compared for equality with this set * @return {@code true} if the specified object is equal to this set */ @@ -125,60 +132,4 @@ } return h; } - - /** - * Removes from this set all of its elements that are contained in the - * specified collection (optional operation). If the specified - * collection is also a set, this operation effectively modifies this - * set so that its value is the asymmetric set difference of - * the two sets. - * - *
This implementation determines which is the smaller of this set - * and the specified collection, by invoking the {@code size} - * method on each. If this set has fewer elements, then the - * implementation iterates over this set, checking each element - * returned by the iterator in turn to see if it is contained in - * the specified collection. If it is so contained, it is removed - * from this set with the iterator's {@code remove} method. If - * the specified collection has fewer elements, then the - * implementation iterates over the specified collection, removing - * from this set each element returned by the iterator, using this - * set's {@code remove} method. - * - *
Note that this implementation will throw an - * {@code UnsupportedOperationException} if the iterator returned by the - * {@code iterator} method does not implement the {@code remove} method. - * - * @param c collection containing elements to be removed from this set - * @return {@code true} if this set changed as a result of the call - * @throws UnsupportedOperationException if the {@code removeAll} operation - * is not supported by this set - * @throws ClassCastException if the class of an element of this set - * is incompatible with the specified collection - * (optional) - * @throws NullPointerException if this set contains a null element and the - * specified collection does not permit null elements - * (optional), - * or if the specified collection is null - * @see #remove(Object) - * @see #contains(Object) - */ - public boolean removeAll(Collection c) { - Objects.requireNonNull(c); - boolean modified = false; - - if (size() > c.size()) { - for (Object e : c) - modified |= remove(e); - } else { - for (Iterator i = iterator(); i.hasNext(); ) { - if (c.contains(i.next())) { - i.remove(); - modified = true; - } - } - } - return modified; - } - } --- old/src/java.base/share/classes/java/util/Collection.java 2019-05-13 17:16:10.000000000 -0700 +++ new/src/java.base/share/classes/java/util/Collection.java 2019-05-13 17:16:10.000000000 -0700 @@ -1,5 +1,5 @@ /* - * 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 @@ -101,6 +101,16 @@ * the specified behavior of underlying {@link Object} methods wherever the * implementor deems it appropriate. * + *
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. + * *
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 @@ -445,7 +455,13 @@ /** * 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 @@ -493,8 +509,14 @@ * 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 @@ -553,8 +575,14 @@ * 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 --- old/src/java.base/share/classes/java/util/Collections.java 2019-05-13 17:16:12.000000000 -0700 +++ new/src/java.base/share/classes/java/util/Collections.java 2019-05-13 17:16:12.000000000 -0700 @@ -1,5 +1,5 @@ /* - * 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 @@ -5379,15 +5379,12 @@ * Returns {@code true} if the two specified collections have no * elements in common. * - *
Care must be exercised if this method is used on collections that - * do not comply with the general contract for {@code Collection}. - * Implementations may elect to iterate over either collection and test - * for containment in the other collection (or to perform any equivalent - * computation). If either collection uses a nonstandard equality test - * (as does a {@link SortedSet} whose ordering is not compatible with - * equals, or the key set of an {@link IdentityHashMap}), both - * collections must use the same nonstandard equality test, or the - * result of this method is undefined. + *
Care must be exercised to ensure that both collections use the + * same membership semantics. The implementation may elect to iterate + * over either collection and test element containment in the other + * collection, or perform any equivalent computation. If the collections + * use different membership semantics, the result of this method is + * undefined. * *
Care must also be exercised when using collections that have
* restrictions on the elements that they may contain. Collection
--- old/src/java.base/share/classes/java/util/IdentityHashMap.java 2019-05-13 17:16:13.000000000 -0700
+++ new/src/java.base/share/classes/java/util/IdentityHashMap.java 2019-05-13 17:16:13.000000000 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2000, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 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
@@ -987,22 +987,6 @@
IdentityHashMap.this.remove(o);
return size != oldSize;
}
- /*
- * Must revert from AbstractSet's impl to AbstractCollection's, as
- * the former contains an optimization that results in incorrect
- * behavior when c is a smaller "normal" (non-identity-based) Set.
- */
- public boolean removeAll(Collection c) {
- Objects.requireNonNull(c);
- boolean modified = false;
- for (Iterator