Summary

Specify the core reflection accessors' behaviors around conversions and access check in the package summary of java.lang.reflect.

Problem

java.lang.reflect has consistent behaviors around conversions and access checks. However, they are poorly documented and have caused some confusions, such as JDK-4283544 for access checks, and JDK-4517644 for conversions.

Solution

Put the accessor behaviors in a central place, chosen to be the package summary of java.lang.reflect. This is a good starting point for package-wide information, and can allow users to see the recommendation to use java.lang.invoke earlier.

This change involves Field and Array accessors, Method.invoke, and Constructor.newInstance.

Specification

See attachments.