src/share/classes/java/util/Map.java

rev 7932 : 7057785: Add note to hashCode() that hash code calculation is optional for self-referential Collection/Map
Reviewed-by: duke

@@ -539,10 +539,15 @@
      * <tt>entrySet()</tt> view.  This ensures that <tt>m1.equals(m2)</tt>
      * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two maps
      * <tt>m1</tt> and <tt>m2</tt>, as required by the general contract of
      * {@link Object#hashCode}.
      *
+     * @apiNote Support for calculation of hash code by self referential
+     * Maps (they either directly or indirectly contain themselves as a key) is
+     * optional. Few Map implementations support calculation of hash code for
+     * self referential instances.
+     *
      * @return the hash code value for this map
      * @see Map.Entry#hashCode()
      * @see Object#equals(Object)
      * @see #equals(Object)
      */