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

Print this page
rev 6197 : [mq]: collections


   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 


  28 /**
  29  * The root interface in the <i>collection hierarchy</i>.  A collection
  30  * represents a group of objects, known as its <i>elements</i>.  Some
  31  * collections allow duplicate elements and others do not.  Some are ordered
  32  * and others unordered.  The JDK does not provide any <i>direct</i>
  33  * implementations of this interface: it provides implementations of more
  34  * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>.  This interface
  35  * is typically used to pass collections around and manipulate them where
  36  * maximum generality is desired.
  37  *
  38  * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
  39  * duplicate elements) should implement this interface directly.
  40  *
  41  * <p>All general-purpose <tt>Collection</tt> implementation classes (which
  42  * typically implement <tt>Collection</tt> indirectly through one of its
  43  * subinterfaces) should provide two "standard" constructors: a void (no
  44  * arguments) constructor, which creates an empty collection, and a
  45  * constructor with a single argument of type <tt>Collection</tt>, which
  46  * creates a new collection with the same elements as its argument.  In
  47  * effect, the latter constructor allows the user to copy any collection,


 436      * @see List#equals(Object)
 437      */
 438     boolean equals(Object o);
 439 
 440     /**
 441      * Returns the hash code value for this collection.  While the
 442      * <tt>Collection</tt> interface adds no stipulations to the general
 443      * contract for the <tt>Object.hashCode</tt> method, programmers should
 444      * take note that any class that overrides the <tt>Object.equals</tt>
 445      * method must also override the <tt>Object.hashCode</tt> method in order
 446      * to satisfy the general contract for the <tt>Object.hashCode</tt> method.
 447      * In particular, <tt>c1.equals(c2)</tt> implies that
 448      * <tt>c1.hashCode()==c2.hashCode()</tt>.
 449      *
 450      * @return the hash code value for this collection
 451      *
 452      * @see Object#hashCode()
 453      * @see Object#equals(Object)
 454      */
 455     int hashCode();
























 456 }


   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 import java.util.function.Predicate;
  29 
  30 /**
  31  * The root interface in the <i>collection hierarchy</i>.  A collection
  32  * represents a group of objects, known as its <i>elements</i>.  Some
  33  * collections allow duplicate elements and others do not.  Some are ordered
  34  * and others unordered.  The JDK does not provide any <i>direct</i>
  35  * implementations of this interface: it provides implementations of more
  36  * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>.  This interface
  37  * is typically used to pass collections around and manipulate them where
  38  * maximum generality is desired.
  39  *
  40  * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
  41  * duplicate elements) should implement this interface directly.
  42  *
  43  * <p>All general-purpose <tt>Collection</tt> implementation classes (which
  44  * typically implement <tt>Collection</tt> indirectly through one of its
  45  * subinterfaces) should provide two "standard" constructors: a void (no
  46  * arguments) constructor, which creates an empty collection, and a
  47  * constructor with a single argument of type <tt>Collection</tt>, which
  48  * creates a new collection with the same elements as its argument.  In
  49  * effect, the latter constructor allows the user to copy any collection,


 438      * @see List#equals(Object)
 439      */
 440     boolean equals(Object o);
 441 
 442     /**
 443      * Returns the hash code value for this collection.  While the
 444      * <tt>Collection</tt> interface adds no stipulations to the general
 445      * contract for the <tt>Object.hashCode</tt> method, programmers should
 446      * take note that any class that overrides the <tt>Object.equals</tt>
 447      * method must also override the <tt>Object.hashCode</tt> method in order
 448      * to satisfy the general contract for the <tt>Object.hashCode</tt> method.
 449      * In particular, <tt>c1.equals(c2)</tt> implies that
 450      * <tt>c1.hashCode()==c2.hashCode()</tt>.
 451      *
 452      * @return the hash code value for this collection
 453      *
 454      * @see Object#hashCode()
 455      * @see Object#equals(Object)
 456      */
 457     int hashCode();
 458 
 459     /**
 460      * Removes all of the elements of this collection which match the provided
 461      * predicate.
 462      *
 463      * @param filter a predicate which returns {@code true} for elements to be
 464      * removed
 465      * @return {@code true} if any elements were removed
 466      * @throws NullPointerException if the specified predicate is null
 467      * @since 1.8
 468      */
 469     public default boolean removeAll(Predicate<? super E> filter) {
 470         Objects.requireNonNull(filter);
 471         boolean removed = false;
 472         Iterator<E> each = iterator();
 473         while (each.hasNext()) {
 474             if (filter.test(each.next())) {
 475                 each.remove();
 476                 removed = true;
 477             }
 478         }
 479 
 480         return removed;
 481     }
 482 }