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

[Stephen Colebourne]

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