On 3/7/18 11:28 PM, David Holmes wrote:
That's an interesting point. Should they also be @CallerSensitive?
Yes.
I hope SM::checkPackageAccess check will be removed some day as we now
have strong encapsulation. The security team has considered this and
requires further investigation.
It may be we have to perform the SM check, but throwing
SecurityException is somewhat contrary to the "no exceptions" approach
of getNestHost().
The SecurityException will only be thrown when security manager is
installed and permission denies. Users are responsible to configure
the security policy to grant proper permission.
I filed an issue to track this:
https://bugs.openjdk.java.net/browse/JDK-8199309
I suggest to make @apiNote in Class::getNestHost as just part of
javadoc.
It can define a section like "Nest Membership" that can be referenced
My understanding is that @apiNote et al were introduced to more
clearly distinguish between the actual specification part of the
Javadoc and other non-normative text. As this is non-normative then
@apiNote seems most appropriate. I presume we can still add a tag to
allow cross-referencing from inside Class itself.
The definition of a nest is a specification that has no issue to include
in the javadoc.
by Lookup class spec.
Cross-referencing internal text fragments across distinct javadoc is
something I thought was not done. ??
I also have some suggested edits that you can
consider:
http://cr.openjdk.java.net/~mchung/valhalla/webrevs/nestmates-spec/
Some of these are okay but this part:
* The source language compiler is responsible for deciding which
classes
* and interfaces are nestmates. For example, the {@code javac} compiler
is quite significant and should not be lost. A source compiler is free
to chose not to use the new attributes (and of course not benefit from
the new access control rules but continue to rely on access-bridges.)
So the user of the API has to be aware of this.
This can be retained in @apiNote.
And in MethodHandles I know there is a dislike of versioning text
"Since JDK 11 ..." (though I see this as no different to using
@since!), but again this new behaviour may or may not be present
depending on the version of the classfiles and the compiler used to
create them, so it is critical to me that this is very clearly stated.
I suppose this could be re-stated in the form:
"If the relationship between nested types is expressed directly
through the {@code NestHost} and {@code NestMembers} attributes (see
the Java Virtual Machine Specification, sections 4.7.28 and 4.7.29),
then the associated {@code Lookup} object provides direct access to
the lookup class and all of its nestmates. Otherwise, access between
nested classes is obtained by the Java compiler creating a wrapper
method to ..."
This is fine too. I still think a @linkplain to Class#nestmates would
be useful.
Mandy
Thanks,
David
Mandy
On 3/6/18 10:12 PM, David Holmes wrote:
The Nestmates CSR request:
https://bugs.openjdk.java.net/browse/JDK-8197445
has been prepared by Dan Smith and myself. Before Proposing this CSR
request it needs to have Reviewers add themselves to it.
(The first reviewer will need to edit the issue to enter their
OpenJDK user name in the "Reviewed by" field. Subsequent reviewers
can simply click on the "Reviewed by" field in the "People" section
and add their user name.
The CSR contains links to all the updated specification documents,
all of which have been previously sent out for review/comment to the
EG (and observers).
Thanks,
David
