87  * a method that might perform invocations, and using an existing
  88  * iterator to examine the collection.
  89  *
  90  * <p>Many methods in Collections Framework interfaces are defined in
  91  * terms of the {@link Object#equals(Object) equals} method.  For example,
  92  * the specification for the {@link #contains(Object) contains(Object o)}
  93  * method says: "returns <tt>true</tt> if and only if this collection
  94  * contains at least one element <tt>e</tt> such that
  95  * <tt>(o==null ? e==null : o.equals(e))</tt>."  This specification should
  96  * <i>not</i> be construed to imply that invoking <tt>Collection.contains</tt>
  97  * with a non-null argument <tt>o</tt> will cause <tt>o.equals(e)</tt> to be
  98  * invoked for any element <tt>e</tt>.  Implementations are free to implement
  99  * optimizations whereby the <tt>equals</tt> invocation is avoided, for
 100  * example, by first comparing the hash codes of the two elements.  (The
 101  * {@link Object#hashCode()} specification guarantees that two objects with
 102  * unequal hash codes cannot be equal.)  More generally, implementations of
 103  * the various Collections Framework interfaces are free to take advantage of
 104  * the specified behavior of underlying {@link Object} methods wherever the
 105  * implementor deems it appropriate.
 106  *







 107  * <p>This interface is a member of the
 108  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 109  * Java Collections Framework</a>.
 110  *
 111  * @implSpec
 112  * The default method implementations (inherited or otherwise) do not apply any
 113  * synchronization protocol.  If a {@code Collection} implementation has a
 114  * specific synchronization protocol, then it must override default
 115  * implementations to apply that protocol.
 116  *
 117  * @param <E> the type of elements in this collection
 118  *
 119  * @author  Josh Bloch
 120  * @author  Neal Gafter
 121  * @see     Set
 122  * @see     List
 123  * @see     Map
 124  * @see     SortedSet
 125  * @see     SortedMap
 126  * @see     HashSet

  87  * a method that might perform invocations, and using an existing
  88  * iterator to examine the collection.
  89  *
  90  * <p>Many methods in Collections Framework interfaces are defined in
  91  * terms of the {@link Object#equals(Object) equals} method.  For example,
  92  * the specification for the {@link #contains(Object) contains(Object o)}
  93  * method says: "returns <tt>true</tt> if and only if this collection
  94  * contains at least one element <tt>e</tt> such that
  95  * <tt>(o==null ? e==null : o.equals(e))</tt>."  This specification should
  96  * <i>not</i> be construed to imply that invoking <tt>Collection.contains</tt>
  97  * with a non-null argument <tt>o</tt> will cause <tt>o.equals(e)</tt> to be
  98  * invoked for any element <tt>e</tt>.  Implementations are free to implement
  99  * optimizations whereby the <tt>equals</tt> invocation is avoided, for
 100  * example, by first comparing the hash codes of the two elements.  (The
 101  * {@link Object#hashCode()} specification guarantees that two objects with
 102  * unequal hash codes cannot be equal.)  More generally, implementations of
 103  * the various Collections Framework interfaces are free to take advantage of
 104  * the specified behavior of underlying {@link Object} methods wherever the
 105  * implementor deems it appropriate.
 106  *
 107  * <p>Some collection operations which perform recursive traversal of the
 108  * collection may fail with an exception for self-referential instances where
 109  * the collection directly or indirectly contains itself. This includes the
 110  * {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
 111  * methods. Implementations may optionally handle the self-referential scenario,
 112  * however most current implementations do not do so.
 113  *
 114  * <p>This interface is a member of the
 115  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 116  * Java Collections Framework</a>.
 117  *
 118  * @implSpec
 119  * The default method implementations (inherited or otherwise) do not apply any
 120  * synchronization protocol.  If a {@code Collection} implementation has a
 121  * specific synchronization protocol, then it must override default
 122  * implementations to apply that protocol.
 123  *
 124  * @param <E> the type of elements in this collection
 125  *
 126  * @author  Josh Bloch
 127  * @author  Neal Gafter
 128  * @see     Set
 129  * @see     List
 130  * @see     Map
 131  * @see     SortedSet
 132  * @see     SortedMap
 133  * @see     HashSet