edition
JDK8(JDK1.8)

Collection interface source code focus
1. The root interface in the set hierarchy. A set represents a group of objects called its elements. Some sets allow repeated elements, while others do not. Some are ordered and some are disordered.

2. The interface class defines various specifications, including method specifications and exception throwing specifications, as well as comparison and hash operations, as well as separator splitter and stream. The methods mainly include three types of query, modification and batch, such as containers (object o), add(E e) and addall (collection <? Extensions E > C) corresponding to query, modification and batch respectively

3. Set operation method of interface definition

4. Some other methods of interface definition

You can see my article splitter

5. Exception thrown by interface definition

Collection interface source code

package java.util;

import java.util.function.Predicate;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;

/**
 * The root interface in the <i>collection hierarchy</i>.  A collection
 * represents a group of objects, known as its <i>elements</i>.  Some
 * collections allow duplicate elements and others do not.  Some are ordered
 * and others unordered.  The JDK does not provide any <i>direct</i>
 * implementations of this interface: it provides implementations of more
 * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>.  This interface
 * is typically used to pass collections around and manipulate them where
 * maximum generality is desired.
 * The root interface in the collection hierarchy. A collection represents a set of objects called its elements.
 * Some collections allow duplicate elements, while others do not.
 * Some are orderly and some are disordered. JDK does not provide any direct implementation of this interface:
 * It provides more specific implementations of sub interfaces such as Set and List.
 * This interface is typically used to pass collections and operate on them where maximum versatility is required.
 * 
 *
 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
 * duplicate elements) should implement this interface directly.
 * Packages or multiple sets (unordered sets that may contain duplicate elements) should implement this interface directly
 *
 * 
 * 
 * <p>All general-purpose <tt>Collection</tt> implementation classes (which
 * typically implement <tt>Collection</tt> indirectly through one of its
 * subinterfaces) should provide two "standard" constructors: a void (no
 * arguments) constructor, which creates an empty collection, and a
 * constructor with a single argument of type <tt>Collection</tt>, which
 * creates a new collection with the same elements as its argument.  In
 * effect, the latter constructor allows the user to copy any collection,
 * producing an equivalent collection of the desired implementation type.
 * There is no way to enforce this convention (as interfaces cannot contain
 * constructors) but all of the general-purpose <tt>Collection</tt>
 * implementations in the Java platform libraries comply.
 * All generic collection implementation classes, which typically implement collections indirectly through one of their sub interfaces, should provide two "standard" constructors:
 * A void (parameterless) constructor that creates an empty Collection and a constructor with a single parameter of type Collection,
 * It creates a new collection whose elements are the same as its parameters.
 * In fact, the latter constructor allows the user to copy any collection, resulting in an equivalent collection of the required implementation types.
 * This Convention cannot be enforced (because interfaces cannot contain constructors), but all common collection implementations in the Java platform library comply with this Convention.
 * 
 * 
 * 
 * 
 *
 * <p>The "destructive" methods contained in this interface, that is, the
 * methods that modify the collection on which they operate, are specified to
 * throw <tt>UnsupportedOperationException</tt> if this collection does not
 * support the operation.  If this is the case, these methods may, but are not
 * required to, throw an <tt>UnsupportedOperationException</tt> if the
 * invocation would have no effect on the collection.  For example, invoking
 * the {@link #addAll(Collection)} method on an unmodifiable collection may,
 * but is not required to, throw the exception if the collection to be added
 * is empty.
 * 
 * The "destructive" methods contained in this interface, that is, methods that modify the collection of their operations,
 * Specifies that an unsupported operationexception is thrown when the operation is not supported by the collection.
 * If this is the case, these methods may (but are not required) if the call has no impact on the collection
 * Throw unsupported operationexception. For example, if the collection to be added is empty,
 * Calling the addAll(Collection) method on a non modifiable collection may (but is not required) throw an exception.
 * 
 * 
 * 
 * 
 * <p><a name="optional-restrictions">
 * Some collection implementations have restrictions on the elements that
 * they may contain.</a>  For example, some implementations prohibit null elements,
 * and some have restrictions on the types of their elements.  Attempting to
 * add an ineligible element throws an unchecked exception, typically
 * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.  Attempting
 * to query the presence of an ineligible element may throw an exception,
 * or it may simply return false; some implementations will exhibit the former
 * behavior and some will exhibit the latter.  More generally, attempting an
 * operation on an ineligible element whose completion would not result in
 * the insertion of an ineligible element into the collection may throw an
 * exception or it may succeed, at the option of the implementation.
 * Such exceptions are marked as "optional" in the specification for this
 * interface.
 * Some collection implementations have restrictions on the elements they may contain.
 * For example, some implementations prohibit empty elements, while others restrict the types of their elements.
 * Attempting to add an unqualified element throws an unchecked exception, usually NullPointerException or ClassCastException.
 * Attempting to query the existence of unqualified elements may throw an exception or only return false;
 * Some implementations will show the former behavior, while others will show the latter behavior.
 * More generally, attempting an operation on an unqualified element whose completion does not cause the unqualified element to be inserted into the collection may throw an exception,
 * Or it may succeed (selected by the implementation). Such exceptions are marked as "optional" in the interface specification.
 * 
 * 
 * 
 * 
 * 
 * <p>It is up to each collection to determine its own synchronization
 * policy.  In the absence of a stronger guarantee by the
 * implementation, undefined behavior may result from the invocation
 * of any method on a collection that is being mutated by another
 * thread; this includes direct invocations, passing the collection to
 * a method that might perform invocations, and using an existing
 * iterator to examine the collection.
 * Each collection determines its own synchronization policy. In the absence of stronger guarantees,
 * Undefined behavior may be caused by calling any method on the collection that another thread is mutating;
 * This includes direct calls, passing collections to methods that might perform calls, and checking collections using existing iterators.
 * 
 * 
 * 
 * 
 *
 * <p>Many methods in Collections Framework interfaces are defined in
 * terms of the {@link Object#equals(Object) equals} method.  For example,
 * the specification for the {@link #contains(Object) contains(Object o)}
 * method says: "returns <tt>true</tt> if and only if this collection
 * contains at least one element <tt>e</tt> such that
 * <tt>(o==null ? e==null : o.equals(e))</tt>."  This specification should
 * <i>not</i> be construed to imply that invoking <tt>Collection.contains</tt>
 * with a non-null argument <tt>o</tt> will cause <tt>o.equals(e)</tt> to be
 * invoked for any element <tt>e</tt>.  Implementations are free to implement
 * optimizations whereby the <tt>equals</tt> invocation is avoided, for
 * example, by first comparing the hash codes of the two elements.  (The
 * {@link Object#hashCode()} specification guarantees that two objects with
 * 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.
 * Many methods in the collection framework interface are defined based on the Object.equals(Object) method.
 * For example, the specification of the contains(Object o) method says, "if and only if this collection contains at least one element e,
 * Make (o==null? e==null:o.equals(e)) return true. "
 * This specification should not be interpreted as implying that Collection.contains is called with a non null parameter o
 * This will cause o.equals(e) to be called on any element e.
 * Implementations are free to implement optimizations to avoid equals calls, for example, by first comparing the hash codes of two elements.
 * Object.hashCode()The specification guarantees that two objects with unequal hash codes cannot be equal.
 * More generally, the implementation of various collection framework interfaces can freely use the specified behavior of the underlying Object method where the implementer thinks it appropriate.
 * 
 * 
 * 
 * 
 * 
 *
 * <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,
 * however most current implementations do not do so.
 * Some collection operations that recursively traverse a collection may fail, but for self referenced instances where the collection contains itself directly or indirectly,
 * An exception occurs. This includes the clone(), equals(), hashCode(), and toString() methods.
 * Implementations can optionally handle self referencing scenarios, but most current implementations do not.
 * 
 * 
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @implSpec
 * The default method implementations (inherited or otherwise) do not apply any
 * synchronization protocol.  If a {@code Collection} implementation has a
 * specific synchronization protocol, then it must override default
 * implementations to apply that protocol.
 * The default method implementation (inheritance or other) does not apply any synchronization protocol. If the Collection implementation has a specific synchronization protocol,
 * It must override the default implementation to apply the protocol.
 *
 * @param <E> the type of elements in this collection
 *
 * @author  Josh Bloch
 * @author  Neal Gafter
 * @see     Set
 * @see     List
 * @see     Map
 * @see     SortedSet
 * @see     SortedMap
 * @see     HashSet
 * @see     TreeSet
 * @see     ArrayList
 * @see     LinkedList
 * @see     Vector
 * @see     Collections
 * @see     Arrays
 * @see     AbstractCollection
 * @since 1.2
 */

public interface Collection<E> extends Iterable<E> {
    // Query Operations query operations

    /**
     * Returns the number of elements in this collection.  If this collection
     * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
     * <tt>Integer.MAX_VALUE</tt>.
     * Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, integer.max is returned_ VALUE
     *
     * @return the number of elements in this collection
     */
    int size();

    /**
     * Returns <tt>true</tt> if this collection contains no elements.
     * Returns true if the collection does not contain any elements.
     *
     * @return <tt>true</tt> if this collection contains no elements
     */
    boolean isEmpty();

    /**
     * Returns <tt>true</tt> if this collection contains the specified element.
     * More formally, returns <tt>true</tt> if and only if this collection
     * contains at least one element <tt>e</tt> such that
     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
     * Returns true if the collection contains the specified element. More formally, if and only if the set contains at least one element e,
     * And (o = = null? e = = null: o.equals (e)), return true.
     * That is, if O is equal to null, judge whether e is equal to null; if O is not equal to null, judge whether it is equal using o.equals(e)
     * 
     *
     * @param o element whose presence in this collection is to be tested The element to test for its presence in this collection
     * @return <tt>true</tt> if this collection contains the specified
     *         element true if this collection contains the specified element
     * @throws ClassCastException if the type of the specified element
     *         is incompatible with this collection If the type of the specified element is incompatible with this collection
     *         (<a href="#optional-restrictions">optional</a>)
     * @throws NullPointerException if the specified element is null and this
     *         collection does not permit null elements If the specified element is null, and this collection does not allow null elements
     *         (<a href="#optional-restrictions">optional</a>)
     */
    boolean contains(Object o);

    /**
     * Returns an iterator over the elements in this collection.  There are no
     * guarantees concerning the order in which the elements are returned
     * (unless this collection is an instance of some class that provides a
     * guarantee).
     * Returns the iterator for the element in this collection.
     * There is no guarantee of the return order of elements (unless this collection is an instance of a class that provides an order guarantee).
     *
     * @return an <tt>Iterator</tt> over the elements in this collection Iterators for elements in this collection
     */
    Iterator<E> iterator();

    /**
     * Returns an array containing all of the elements in this collection.
     * If this collection makes any guarantees as to what order its elements
     * are returned by its iterator, this method must return the elements in
     * the same order.
     * Returns an array containing all elements in this collection. If this collection guarantees the order in which its iterators return its elements,
     * This method must be in the same order.
     * 
     * 
     *
     * <p>The returned array will be "safe" in that no references to it are
     * maintained by this collection.  (In other words, this method must
     * allocate a new array even if this collection is backed by an array).
     * The caller is thus free to modify the returned array.
     * The returned array will be "safe" because this collection does not maintain a reference to it.
     * (In other words, even if this collection is supported by arrays, this method must allocate new arrays). Therefore, the caller is free to modify the returned array.
     * 
     *
     * <p>This method acts as bridge between array-based and collection-based
     * APIs.  This method acts as a bridge between the API of the array and the API of the collection.
     *
     * @return an array containing all of the elements in this collection
     * An array containing all the elements in this collection
     */
    Object[] toArray();

    /**
     * Returns an array containing all of the elements in this collection;
     * the runtime type of the returned array is that of the specified array.
     * If the collection fits in the specified array, it is returned therein.
     * Otherwise, a new array is allocated with the runtime type of the
     * specified array and the size of this collection.
     * Returns an array containing all elements in this collection; The runtime type of the returned array is the runtime type of the specified array.
     * If the collection fits the specified array, all elements in the given array are returned.
     * Otherwise, a new array is allocated using the runtime type of the specified array and the size of this collection.
     *
     * 
     * 
     * 
     * 
     * <p>If this collection fits in the specified array with room to spare
     * (i.e., the array has more elements than this collection), the element
     * in the array immediately following the end of the collection is set to
     * <tt>null</tt>.  (This is useful in determining the length of this
     * collection <i>only</i> if the caller knows that this collection does
     * not contain any <tt>null</tt> elements.)
     * If this collection fits a specified array with free space (that is, the array has more elements than this collection),
     * The elements in the array immediately after the end of the collection will be set to null.
     * (This is useful in determining the length of this collection only if the caller knows that this collection does not contain any empty elements.)
     * 
     * 
     *
     * <p>If this collection makes any guarantees as to what order its elements
     * are returned by its iterator, this method must return the elements in
     * the same order. If this collection guarantees the order in which the iterator returns elements, this method must return elements in the same order
     *
     * <p>Like the {@link #toArray()} method, this method acts as bridge between
     * array-based and collection-based APIs.  Further, this method allows
     * precise control over the runtime type of the output array, and may,
     * under certain circumstances, be used to save allocation costs.
     * Like the toArray() method, this method acts as a bridge between the API of the array and the API of the collection.
     * In addition, this method allows precise control over the runtime type of the output array and can be used to save allocation costs in some cases.
     * 
     *
     * <p>Suppose <tt>x</tt> is a collection known to contain only strings.
     * The following code can be used to dump the collection into a newly
     * allocated array of <tt>String</tt>: 
     * Suppose x is a collection known to contain only strings. The following code can be used to dump a collection into a newly allocated string array
     *
     * <pre>
     *     String[] y = x.toArray(new String[0]);</pre>
     *
     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
     * <tt>toArray()</tt>.
     * Note that toArray(new Object[0]) is exactly the same as toArray().
     *
     * @param <T> the runtime type of the array to contain the collection The runtime type of the array containing the collection
     * @param a the array into which the elements of this collection are to be
     *        stored, if it is big enough; otherwise, a new array of the same
     *        runtime type is allocated for this purpose.
     *       a The array to which the elements of this collection will be stored (if large enough); Otherwise, a new array of the same runtime type is allocated for this purpose.
     * @return an array containing all of the elements in this collection An array containing all the elements in this collection
     * @throws ArrayStoreException if the runtime type of the specified array
     *         is not a supertype of the runtime type of every element in
     *         this collection
     *          If the runtime type of the specified array is not a supertype of the runtime type of each element in this collection
     * @throws NullPointerException if the specified array is null If the specified array is empty
     */
    <T> T[] toArray(T[] a);

    // Modification Operations

    /**
     * Ensures that this collection contains the specified element (optional
     * operation).  Returns <tt>true</tt> if this collection changed as a
     * result of the call.  (Returns <tt>false</tt> if this collection does
     * not permit duplicates and already contains the specified element.)<p>
     * Optionally, ensure that this collection contains the specified element. Returns true if the collection changes due to a call.
     * (Returns false if the collection does not allow duplicates and already contains the specified element.)
     * 
     * 
     * 
     *
     * Collections that support this operation may place limitations on what
     * elements may be added to this collection.  In particular, some
     * collections will refuse to add <tt>null</tt> elements, and others will
     * impose restrictions on the type of elements that may be added.
     * Collection classes should clearly specify in their documentation any
     * restrictions on what elements may be added.<p>
     * Collections that support this operation may set restrictions on the elements that can be added to this collection.
     * In particular, some collections will refuse to add null elements, while others will impose restrictions on the types of elements that may be added.
     * Collection classes should explicitly specify any restrictions on elements that may be added in their documentation.
     * 
     * 
     * 
     *
     * If a collection refuses to add a particular element for any reason
     * other than that it already contains the element, it <i>must</i> throw
     * an exception (rather than returning <tt>false</tt>).  This preserves
     * the invariant that a collection always contains the specified element
     * after this call returns.
     * If the collection refuses to add a specific element for any reason, not because it already contains the element,
     * It must throw an exception (instead of returning false).
     * This preserves the invariance that the collection always contains the specified element after the call returns.
     * 
     * 
     *
     * @param e element whose presence in this collection is to be ensured Elements to ensure that they exist in this collection (elements to be added to the collection)
     * @return <tt>true</tt> if this collection changed as a result of the
     *         call true if this collection changes due to a call
     * @throws UnsupportedOperationException if the <tt>add</tt> operation
     *         is not supported by this collection If this collection does not support add operations
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this collection If the class of the specified element prevents it from being added to this collection
     * @throws NullPointerException if the specified element is null and this
     *         collection does not permit null elements If the specified element is null, and this collection does not allow null elements
     * @throws IllegalArgumentException if some property of the element
     *         prevents it from being added to this collection If some attributes of an element prevent it from being added to this collection
     * @throws IllegalStateException if the element cannot be added at this
     *         time due to insertion restrictions If the element cannot be added at this time due to insertion restrictions (the container is full)
     */
    boolean add(E e);

    /**
     * Removes a single instance of the specified element from this
     * collection, if it is present (optional operation).  More formally,
     * removes an element <tt>e</tt> such that
     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>, if
     * this collection contains one or more such elements.  Returns
     * <tt>true</tt> if this collection contained the specified element (or
     * equivalently, if this collection changed as a result of the call).
     * Optionally, removes a single instance of the specified element from the collection, if it exists.
     * More formally, if the collection contains one or more such elements, delete element e,
     * So that (o==null? e==null:o.equals(e)).
     * Returns true if the collection contains the specified element (or an equivalent value if the collection changes due to a call).
     * 
     * 
     *
     * @param o element to be removed from this collection, if present The element (if any) to remove from this collection
     * @return <tt>true</tt> if an element was removed as a result of this call true if this call causes the element to be deleted
     * @throws ClassCastException if the type of the specified element
     *         is incompatible with this collection
     *         (<a href="#optional-restrictions">optional</a>)
     * @throws NullPointerException if the specified element is null and this
     *         collection does not permit null elements
     *         (<a href="#optional-restrictions">optional</a>)
     * @throws UnsupportedOperationException if the <tt>remove</tt> operation
     *         is not supported by this collection If this collection does not support delete operations
     */
    boolean remove(Object o);


    // Bulk Operations

    /**
     * Returns <tt>true</tt> if this collection contains all of the elements
     * in the specified collection.
     * Returns true if this collection contains all elements in the specified collection.
     *
     * @param  c collection to be checked for containment in this collection To check whether this collection contains
     * @return <tt>true</tt> if this collection contains all of the elements
     *         in the specified collection true if this collection contains all elements in the specified collection
     * @throws ClassCastException if the types of one or more elements
     *         in the specified collection are incompatible with this
     *         collection
     *         (<a href="#optional-restrictions">optional</a>)
     * @throws NullPointerException if the specified collection contains one
     *         or more null elements and this collection does not permit null
     *         elements
     *         (<a href="#optional-restrictions">optional</a>),
     *         or if the specified collection is null.
     * @see    #contains(Object)
     */
    boolean containsAll(Collection<?> c);

    /**
     * Adds all of the elements in the specified collection to this collection
     * (optional operation).  The behavior of this operation is undefined if
     * the specified collection is modified while the operation is in progress.
     * (This implies that the behavior of this call is undefined if the
     * specified collection is this collection, and this collection is
     * nonempty.)
     * Optionally, add all elements in the specified collection to this collection.
     * If the specified collection is modified during the operation, the behavior of the operation is undefined.
     * (This means that if the specified collection is this collection and this collection is non empty, the behavior of this call is undefined.)
     * That is, the incoming set c is itself, that is, addAll(this), which will lead to unknown behavior
     * 
     * 
     * 
     *
     * @param c collection containing elements to be added to this collection c The collection that contains the elements to add to this collection
     * @return <tt>true</tt> if this collection changed as a result of the call true if this collection changes due to a call
     * @throws UnsupportedOperationException if the <tt>addAll</tt> operation
     *         is not supported by this collection
     * @throws ClassCastException if the class of an element of the specified
     *         collection prevents it from being added to this collection
     * @throws NullPointerException if the specified collection contains a
     *         null element and this collection does not permit null elements,
     *         or if the specified collection is null
     * @throws IllegalArgumentException if some property of an element of the
     *         specified collection prevents it from being added to this
     *         collection
     * @throws IllegalStateException if not all the elements can be added at
     *         this time due to insertion restrictions
     * @see #add(Object)
     */
    boolean addAll(Collection<? extends E> c);

    /**
     * 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.
     * Optionally, delete all elements of this collection that are also contained in the specified collection.
     * When this call returns, the collection will not contain the same elements as the specified collection
     * 
     * @param c collection containing elements to be removed from this collection c The collection that contains the elements you want to remove from this collection
     * @return <tt>true</tt> if this collection changed as a result of the
     *         call true if this collection changes due to a call
     * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
     *         is not supported by this collection
     * @throws ClassCastException if the types of one or more elements
     *         in this collection are incompatible with the specified
     *         collection
     *         (<a href="#optional-restrictions">optional</a>)
     * @throws NullPointerException if this collection contains one or more
     *         null elements and the specified collection does not support
     *         null elements
     *         (<a href="#optional-restrictions">optional</a>),
     *         or if the specified collection is null
     * @see #remove(Object)
     * @see #contains(Object)
     */
    boolean removeAll(Collection<?> c);

    /**
     * Removes all of the elements of this collection that satisfy the given
     * predicate.  Errors or runtime exceptions thrown during iteration or by
     * the predicate are relayed to the caller.
     * Delete all elements in this collection that meet the given Predicate.
     * Errors or runtime exceptions thrown during iterations or predictions are forwarded to the caller.
     * 
     *
     * 
     * @implSpec
     * The default implementation traverses all elements of the collection using
     * its {@link #iterator}.  Each matching element is removed using
     * {@link Iterator#remove()}.  If the collection's iterator does not
     * support removal then an {@code UnsupportedOperationException} will be
     * thrown on the first matching element.
     * The default implementation uses its iterator to traverse all elements of the collection.
     * Delete each matching element using iterator.remove().
     * If the collection's iterator does not support deletion, an unsupported operationexception is thrown on the first matching element.
     * 
     * predicate Relative to a certain matching rule, the passed element returns true or false, indicating that it complies with the rule and does not comply with the rule
     *
     * @param filter a predicate which returns {@code true} for elements to be
     *        removed Elements that pass in a predicate and return true will be deleted. Predicate is a matching rule
     * @return {@code true} if any elements were removed
     * @throws NullPointerException if the specified filter is null
     * @throws UnsupportedOperationException if elements cannot be removed
     *         from this collection.  Implementations may throw this exception if a
     *         matching element cannot be removed or if, in general, removal is not
     *         supported.
     * @since 1.8
     */
    default boolean removeIf(Predicate<? super E> filter) {
        Objects.requireNonNull(filter);
        boolean removed = false;
        final Iterator<E> each = iterator();
        while (each.hasNext()) {
            if (filter.test(each.next())) {
                each.remove();
                removed = true;
            }
        }
        return removed;
    }

    /**
     * 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.
     * Keep only the elements in this collection that are included in the specified collection (optional).
     * In other words, all elements not contained in the specified collection are deleted from the collection.
     * 
     *
     * @param c collection containing elements to be retained in this collection The collection that contains the elements you want to keep in this collection
     * @return <tt>true</tt> if this collection changed as a result of the call true if this collection changes due to a call
     * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
     *         is not supported by this collection
     * @throws ClassCastException if the types of one or more elements
     *         in this collection are incompatible with the specified
     *         collection
     *         (<a href="#optional-restrictions">optional</a>)
     * @throws NullPointerException if this collection contains one or more
     *         null elements and the specified collection does not permit null
     *         elements
     *         (<a href="#optional-restrictions">optional</a>),
     *         or if the specified collection is null
     * @see #remove(Object)
     * @see #contains(Object)
     */
    boolean retainAll(Collection<?> c);

    /**
     * Removes all of the elements from this collection (optional operation).
     * The collection will be empty after this method returns.
     * Optionally, delete all elements from this collection. When this method returns, the collection will be empty.
     * 
     * @throws UnsupportedOperationException if the <tt>clear</tt> operation
     *         is not supported by this collection
     */
    void clear();


    // Comparison and hash ing

    /**
     * Compares the specified object with this collection for equality. <p>
     * Compares whether the specified object is equal to this collection
     *
     * While the <tt>Collection</tt> interface adds no stipulations to the
     * general contract for the <tt>Object.equals</tt>, programmers who
     * implement the <tt>Collection</tt> interface "directly" (in other words,
     * create a class that is a <tt>Collection</tt> but is not a <tt>Set</tt>
     * or a <tt>List</tt>) must exercise care if they choose to override the
     * <tt>Object.equals</tt>.  It is not necessary to do so, and the simplest
     * course of action is to rely on <tt>Object</tt>'s implementation, but
     * the implementor may wish to implement a "value comparison" in place of
     * the default "reference comparison."  (The <tt>List</tt> and
     * <tt>Set</tt> interfaces mandate such value comparisons.)<p>
     * Although the collection interface does not add any provisions to the general convention of Object.equals,
     * But programmers who "directly" implement the collection interface (in other words, create a class that belongs to a collection but is not a collection or list)
     * You must be careful when choosing to override Object.equals.
     * There is no need to do this. The simplest way is to rely on the implementation of objects,
     * However, implementers may want to implement "value comparison" instead of the default "reference comparison". (list and collection interfaces require such value comparisons.)
     * 
     * (The default implementation of Object.equals is reference comparison)
     * 
     * 
     * 
     * The general contract for the <tt>Object.equals</tt> method states that
     * equals must be symmetric (in other words, <tt>a.equals(b)</tt> if and
     * only if <tt>b.equals(a)</tt>).  The contracts for <tt>List.equals</tt>
     * and <tt>Set.equals</tt> state that lists are only equal to other lists,
     * and sets to other sets.  Thus, a custom <tt>equals</tt> method for a
     * collection class that implements neither the <tt>List</tt> nor
     * <tt>Set</tt> interface must return <tt>false</tt> when this collection
     * is compared to any list or set.  (By the same logic, it is not possible
     * to write a class that correctly implements both the <tt>Set</tt> and
     * <tt>List</tt> interfaces.)
     * Object.equals The general convention for methods states that equals must be symmetric (in other words, a.equals (b))
     * At the same time, b.equals (a)).
     * List.equals The Convention of and Set.equals means that the list is only equal to other lists,
     * The set is equal to other sets. Therefore, when comparing this set with any list or set,
     * The custom equals method of a collection class that implements neither the List interface nor the Set interface must return false.
     * (According to the same logic, it is impossible to write classes that correctly implement the Set and List interfaces at the same time.)
     * 
     * 
     * 
     * 
     *
     * @param o object to be compared for equality with this collection The object to compare with this collection for equality
     * @return <tt>true</tt> if the specified object is equal to this
     * collection true if the specified object is equal to this collection
     *
     * @see Object#equals(Object)
     * @see Set#equals(Object)
     * @see List#equals(Object)
     */
    boolean equals(Object o);

    /**
     * Returns the hash code value for this collection.  While the
     * <tt>Collection</tt> interface adds no stipulations to the general
     * contract for the <tt>Object.hashCode</tt> method, programmers should
     * take note that any class that overrides the <tt>Object.equals</tt>
     * method must also override the <tt>Object.hashCode</tt> method in order
     * to satisfy the general contract for the <tt>Object.hashCode</tt> method.
     * In particular, <tt>c1.equals(c2)</tt> implies that
     * <tt>c1.hashCode()==c2.hashCode()</tt>.
     * Returns the hash code value of this collection. Although the collection interface does not add any provisions to the general convention of the Object.hashCode method,
     * However, programmers should note that any class that overrides the Object.equals method must also override the Object.hashCode method,
     * To meet the general convention of the Object.hashCode method.
     * In particular, c1.equals(c2) means c1.hashCode()==c2.hashCode().
     * 
     * 
     *
     * @return the hash code value for this collection Hash code value for this collection
     *
     * @see Object#hashCode()
     * @see Object#equals(Object)
     */
    int hashCode();

    /**
     * Creates a {@link Spliterator} over the elements in this collection.
     * Create a splitter on an element in this collection.
     * 
     * 
     *
     * Implementations should document characteristic values reported by the
     * spliterator.  Such characteristic values are not required to be reported
     * if the spliterator reports {@link Spliterator#SIZED} and this collection
     * contains no elements.
     * The implementation should record the characteristic values reported by the splitter.
     * If the splitter reports splitter. Size (), and this collection does not contain any elements,
     * Such characteristic values do not need to be reported.
     * 
     * 
     *
     * <p>The default implementation should be overridden by subclasses that
     * can return a more efficient spliterator.  In order to
     * preserve expected laziness behavior for the {@link #stream()} and
     * {@link #parallelStream()}} methods, spliterators should either have the
     * characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
     * <em><a href="Spliterator.html#binding">late-binding</a></em>.
     * If none of these is practical, the overriding class should describe the
     * spliterator's documented policy of binding and structural interference,
     * and should override the {@link #stream()} and {@link #parallelStream()}
     * methods to create streams using a {@code Supplier} of the spliterator,
     * as in:
     * The default implementation should be overridden by subclasses that can return more efficient splitters.
     * To maintain the expected lazy behavior of the stream() and parallelStream() methods,
     * The splitter should have IMMUTABLE or current attributes, or late binding.
     * If these are not practical, the rewriting class should describe the binding of the splitter and the documented strategy of structural interference,
     * And the stream() and parallelStream() methods should be overridden to create a stream using the splitter's Supplier, as shown in:
     * 
     * 
     * <pre>{@code
     *     Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
     * }</pre>
     * <p>These requirements ensure that streams produced by the
     * {@link #stream()} and {@link #parallelStream()} methods will reflect the
     * contents of the collection as of initiation of the terminal stream
     * operation. 
     * These requirements ensure that the streams generated by the stream()} and parallelStream() methods will reflect the content collected when the terminal stream operation starts.
     *
     * @implSpec
     * The default implementation creates a
     * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
     * from the collections's {@code Iterator}.  The spliterator inherits the
     * <em>fail-fast</em> properties of the collection's iterator.
     * The default implementation creates a late bound splitter from the Iterator of the collection. The splitter inherits the fail fast property of the collection Iterator.
     * 
     * 
     * <p>
     * The created {@code Spliterator} reports {@link Spliterator#SIZED}.
     * Created splitter report splitter.sized
     *
     * @implNote
     * The created {@code Spliterator} additionally reports Created splitter plus report
     * {@link Spliterator#SUBSIZED}.
     *
     * <p>If a spliterator covers no elements then the reporting of additional
     * characteristic values, beyond that of {@code SIZED} and {@code SUBSIZED},
     * does not aid clients to control, specialize or simplify computation.
     * However, this does enable shared use of an immutable and empty
     * spliterator instance (see {@link Spliterators#emptySpliterator()}) for
     * empty collections, and enables clients to determine if such a spliterator
     * covers no elements.
     * If the splitter does not contain any elements, except size and SUBSIZED
     * The report of other eigenvalues will not help the client control, specialize or simplify the calculation.
     * However, this does allow immutable empty splitter instances to be shared for empty collections
     * (See splitters. Emptysplitters (),
     * And allows the client to determine whether such a splitter does not contain any elements.
     * 
     * 
     *
     * @return a {@code Spliterator} over the elements in this collection
     * @since 1.8
     */
    @Override
    default Spliterator<E> spliterator() {
        return Spliterators.spliterator(this, 0);
    }

    /**
     * Returns a sequential {@code Stream} with this collection as its source.
     * Returns a sequence Stream with the collection as its source.
     *
     * <p>This method should be overridden when the {@link #spliterator()}
     * method cannot return a spliterator that is {@code IMMUTABLE},
     * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
     * for details.)
     * When the splitter() method cannot return IMMUTABLE
     * CONCURRENT Or late bound splitter, this method should be overridden.
     * (For more information, see splitter()
     *
     * @implSpec
     * The default implementation creates a sequential {@code Stream} from the
     * collection's {@code Spliterator}.
     * The default implementation creates a sequence Stream from the splitter of the collection.
     * 
     *
     * @return a sequential {@code Stream} over the elements in this collection
     * @since 1.8
     */
    default Stream<E> stream() {
        return StreamSupport.stream(spliterator(), false);
    }

    /**
     * Returns a possibly parallel {@code Stream} with this collection as its
     * source.  It is allowable for this method to return a sequential stream.
     * Returns a Stream that may be parallel to this collection as its source. This method allows sequential streams to be returned.
     * 
     * 
     * <p>This method should be overridden when the {@link #spliterator()}
     * method cannot return a spliterator that is {@code IMMUTABLE},
     * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
     * for details.)
     * When the splitter() method cannot return IMMUTABLE
     * CONCURRENT Or late bound splitter, this method should be overridden.
     * (For more information, see splitter()).
     * 
     *
     * @implSpec
     * The default implementation creates a parallel {@code Stream} from the
     * collection's {@code Spliterator}.
     * The default implementation creates a parallel Stream from the splitter of the collection.
     *
     * @return a possibly parallel {@code Stream} over the elements in this
     * collection Possible parallel streams on elements in this collection
     * @since 1.8
     */
    default Stream<E> parallelStream() {
        return StreamSupport.stream(spliterator(), true);
    }
}