Clarifying record reflective support

[Dan Smith]

> On Dec 3, 2019, at 9:35 AM, John Rose <john.r.rose at oracle.com> wrote:
> 
> I have two concerns concerning JVM behavior:
> 
> 1. Keep class file loading fast and simple.

> 2. Perform deeper checks only when reflection is performed.

We just discussed on the phone, this is consistent with the consensus.

> This subtly affects the reflective API points which return information that
> depends on classfile attributes (when, as is often the case, such attributes cannot
> be fully validated at class load time).  Such API points as getInnerClasses and
> getRecordComponents must be allowed to throw errors for “partially broken”
> class files.
> 
> (Do we need a specific term for “partially broken” here? We might say
> “reflectively invalid” I suppose.)
> 
> The javadoc is relatively silent about reflectively invalid class files,
> but don’t take that as evidence that failure is impossible.
> 
> Should getRC document failure modes?  Maybe, but if they are just the
> same as those affecting getMethods, getInnerClasses, etc., there’s no need
> to.

Yes, I've been trying to articulate this point in these discussions, but haven't quite put my finger on it. There are *many* undocumented ways in which reflection can fail on class files that don't conform to the expected format. We could decide to make these failure modes explicit, but that's a big job; in the mean time we should be careful not to apply more scrutiny to the specification of 'isRecord' than we do to every other method in java.lang.Class.

So,

Fine: "isRecord returns true if the class extends java.lang.Record and has a Record attribute." (a little more detailed than most reflection methods, but that's probably good)

Overkill: "isRecord returns true if the class extends java.lang.Record and has a Record attribute that conforms to the following rules ..."