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

[Martin Buchholz]

This isn't just about hashCode - I'm not sure why you are singling it out.
 What about toString?  Or really, any recursive ("deep") algorithm.  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
>
>