After a number of minor editing tweaks to Class and MethodHandles, and
the more significant addition of the Security manager checks to Class,
the specs have again been updated.
http://cr.openjdk.java.net/~dholmes/8010319/specs/
I will propose the CSR request now so that we can start to get feedback
from that process.
Thanks for all the feedback so far.
David
On 9/03/2018 6:45 AM, David Holmes wrote:
Thanks Mandy. We'll take the javadoc editing discussion off-list and
I'll come back to the EG when any changes are made.
David
On 9/03/2018 5:33 AM, mandy chung wrote:
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
