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

[Mike Duigou]

On Aug 28 2013, at 11:48 , Martin Buchholz wrote:

> This isn't just about hashCode - I'm not sure why you are singling it out.  What about toString?

A reasonable point. The bug reports are just about as common for toString() being "broken" for self-referential collections.

>  Or really, any recursive ("deep") algorithm.

A class level note then for specific classes? A general warning on the interfaces regarding self-referential being optional?

Mike

>  And the typical failure mode is inflooping or stack overflow. 
> 
> 
> On Wed, Aug 28, 2013 at 8:49 AM, Mike Duigou <mike.duigou at oracle.com> wrote:
> 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
> 
>