changeset 8274:8cfb2bddd95e

7057785: Add note about optional support of recursive methods for self-referential Collection/Map Reviewed-by: scolebourne, darcy, mduigou Contributed-by: Stephen Colebourne <scolebourne@joda.org>
author mduigou
date Mon, 30 Sep 2013 15:50:06 -0700
parents bf52ea6bd9eb
children f2e2326f787b
files src/share/classes/java/util/Collection.java src/share/classes/java/util/Map.java
diffstat 2 files changed, 18 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Collection.java	Tue Oct 01 17:15:43 2013 +0400
+++ b/src/share/classes/java/util/Collection.java	Mon Sep 30 15:50:06 2013 -0700
@@ -104,6 +104,13 @@
  * the specified behavior of underlying {@link Object} methods wherever the
  * implementor deems 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.
+ *
  * <p>This interface is a member of the
  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  * Java Collections Framework</a>.
--- a/src/share/classes/java/util/Map.java	Tue Oct 01 17:15:43 2013 +0400
+++ b/src/share/classes/java/util/Map.java	Mon Sep 30 15:50:06 2013 -0700
@@ -86,10 +86,6 @@
  * Such exceptions are marked as "optional" in the specification for this
  * interface.
  *
- * <p>This interface is a member of the
- * <a href="{@docRoot}/../technotes/guides/collections/index.html">
- * Java Collections Framework</a>.
- *
  * <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 #containsKey(Object)
@@ -107,6 +103,17 @@
  * the specified behavior of underlying {@link Object} methods wherever the
  * implementor deems it appropriate.
  *
+ * <p>Some map operations which perform recursive traversal of the map may fail
+ * with an exception for self-referential instances where the map 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.
+ *
+ * <p>This interface is a member of the
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
+ * Java Collections Framework</a>.
+ *
  * @param <K> the type of keys maintained by this map
  * @param <V> the type of mapped values
  *