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

[Mike Duigou]

Thanks Stephen,

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

Mike

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