RFR: 7057785 : (xs) Add note to hashCode() that support for self referential is optional

Mike Duigou mike.duigou at oracle.com
Wed Aug 28 15:49:13 UTC 2013

Thanks Stephen,

I am fine with your wording. Any other votes or suggested wordings?


On Aug 28 2013, at 02:55 , Stephen Colebourne wrote:

> I lke the idea, but the wording feels a little opaque as the result is
> typically StackOverflow.
> Also, I prefer a style with the @apiNote on a line of its own, rather
> like a heading. It makes the documentation easier to read in source
> code, and has no effect on the output Javadoc.
> @apiNote
> If the Collection is self-referential, where it directly or indirectly
> contains itself, then the calculation of hashCode may fail with an
> exception. Implementations may optionally try to handle this scenario,
> however most current implementations do not do so.
> Stephen
> On 28 August 2013 03:06, Mike Duigou <mike.duigou at oracle.com> wrote:
>> Hello all;
>> Fairly frequently it is reported that various Collection/Map implementations of hashCode() fail when the instance directly or indirectly contains itself. For a variety of reasons, mostly performance and resource related, most implementations choose not to support calculation of hash codes for self-referential collections. This is not likely to change. So to reduce confusion and "bug" reports I am proposing a non-normative @apiNote be added to Collection and HashMap. The text of the proposed note is:
>>> Support for calculation of hash code by self referential {Collection|Map}s (they either directly or indirectly contain themselves) is optional. Few Collection implementations support calculation of hash code for self referential instances.
>> http://cr.openjdk.java.net/~mduigou/JDK-7057785/0/webrev/
>> Cheers,
>> Mike

More information about the core-libs-dev mailing list