Copyright © 2018 Oracle America, Inc. Legal Notice.
JEP 181 proposes changes to the Java Virtual Machine Specification to allow access to private class members from related "nestmate" classes. This document proposes accompanying changes to the Java Language Specification in order to accurately describe the new runtime behavior of method invocation.
For programs that contain consistently-compiled classes, there is no change in language behavior.
...
A binary representation for a class or interface must also contain all of the following:
...
Every nested class and nested interface must have a symbolic reference to each of its immediately enclosing class enclosing classes (8.1.3).
Every class must contain symbolic references to all of its member types (8.5), and to all local and anonymous classes that appear in its methods, constructors, static initializers, instance initializers, and field initializers.
Every interface must contain symbolic references to all of its member types (9.5), and to all local and anonymous classes that appear in its default methods and field initializers.
It was already true that deeply-nested classes would refer to all of their enclosing classes (per the specification of the InnerClasses attribute). We state that here for clarity. The NestHost attribute can refer to the top-level enclosing class without adding any new references to the class file.
We could also assert that a top-level class contains references to each of its enclosed classes, no matter how deeply nested. But this is not true of the InnerClasses attribute, and we do not wish to force implementations to use the NestMembers attribute. They are free to do so if they wish.
...
...
The following compile-time information is then associated with the method invocation for use at run time:
The name of the method.
The qualifying type of the method invocation (13.1).
The number of parameters and the compile-time parameter types, in order.
The compile-time result.
The invocation mode, computed as follows:
static modifier, then the invocation mode is static.private modifier, then the invocation mode is nonvirtual.super . Identifier or of the form TypeName . super . Identifier, then the invocation mode is super.interface.virtual.We no longer use the nonvirtual invocation mode. private method invocations have invocation mode virtual and behave just like other method invocations. (With the caveat that, per the rules below, a private method will be selected directly without performing a search for a different overriding method.)
...
The strategy for method lookup depends on the invocation mode.
As in section 15.12.4.3, let T be the qualifying type of the method invocation, let m be the method found in T or a supertype of T, and let C be the class or interface that declares m.
If the invocation mode is static, no target reference is needed and overriding is not allowed. Method m of class T class or interface C is the one to be invoked.
Otherwise, an instance method is to be invoked and there is a target reference. If the target reference is null, a NullPointerException is thrown at this point. Otherwise, the target reference is said to refer to a target object and will be used as the value of the keyword this in the invoked method. The other four three possibilities for the invocation mode are then considered.
If the invocation mode is nonvirtual, overriding is not allowed. Method m of class T is the one to be invoked.
If the invocation mode is super, then method m of class or interface C is the one to be invoked. If m is abstract, an AbstractMethodError is thrown.
This is a simplification not directly tied to nestmates: we already located m in T or a supertype of T (15.12.4.3). There is no need to do so again as part of a "dynamic lookup process", as described below.
Otherwise, if the invocation mode is virtual, and T and m jointly indicate a signature polymorphic method (15.12.3), then the target object is an instance of java.lang.invoke.MethodHandle or java.lang.invoke.VarHandle. The target object encapsulates state which is matched against the information associated with the method invocation at compile time. Details of this matching are given in The Java Virtual Machine Specification, Java SE 9 Edition and the Java SE Platform API. If matching succeeds, then either the method referenced by the java.lang.invoke.MethodHandle instance is directly and immediately invoked, or the variable represented by the java.lang.invoke.VarHandle instance is directly and immediately accessed, and in either case the procedure in 15.12.4.5 is not executed. If matching fails, then a java.lang.invoke.WrongMethodTypeException is thrown.
Otherwise, the invocation mode is interface or virtual.
If the method m of class or interface C is private, then it is the method to be invoked.
Otherwise, the invocation mode is overriding may occurinterface, virtual, or super, and. A and a dynamic method lookup is used. The dynamic lookup process starts from a class S, determined as follows: R, the actual run-time class of the target object.
interface or virtual, then S is initially the actual run-time class R of the target object.
This is true even if the target object is an array instance. (Note that for invocation modeinterface, R necessarily implements T; for invocation modevirtual, R is necessarily either T or a subclass of T.)
super, then S is initially the qualifying type (13.1) of the method invocation.Note that for invocation mode
interface, R necessarily implements T; for invocation modevirtual, R is necessarily either T or a subclass of T. If the target object is an array, then R is a "class" representing an array type.
The dynamic method lookup uses the following procedure to search class S, and then the superclasses and superinterfaces of class S, as necessary, for method m.
Let X be the compile-time type of the target reference of the method invocation. Let S be a class to search, beginning with R. Then:
If the invocation mode is super or interface, then this is the method to be invoked, and the procedure terminates.
If the invocation mode is virtual, and the declaration in S overrides X.m (8.4.8.1), then the method declared in S is the method to be invoked, and the procedure terminates.
Otherwise, if S has a superclass, the lookup procedure of steps 1 and 2 is performed recursively using the direct superclass of S in place of S; the method to be invoked, if any, is the result of the recursive invocation of this lookup procedure.
If no method is found by the previous two steps, the superinterfaces of S are searched for a suitable method.
A set of candidate methods is considered with the following properties: i) each method is declared in a (direct or indirect) superinterface of S R; ii) each method has the name and descriptor required by the method invocation; iii) each method is non-static and non-private; iv) for each method, where the method's declaring interface is I, there is no other method satisfying (i) through (iii) that is declared in a subinterface of I.
If this set contains a default method, one such method is the method to be invoked. Otherwise, an abstract method in the set is selected as the method to be invoked.
Dynamic method lookup may cause the following errors to occur:
abstract, an AbstractMethodError is thrown.default, and more than one default method appears in the set of candidates in step 3 above, an IncompatibleClassChangeError is thrown.interface and the selected method is publicpublic nor private, an IllegalAccessError is thrown.The above procedure (if it terminates without error) will find a non-abstract, accessible method to invoke, provided that all classes and interfaces in the program have been consistently compiled. However, if this is not the case, then various errors may occur, as specified above; additional details about the behavior of the Java Virtual Machine under these circumstances are given by The Java Virtual Machine Specification, Java SE 9 Edition.
The dynamic lookup process, while described here explicitly, will often be implemented implicitly, for example as a side-effect of the construction and use of per-class method dispatch tables, or the construction of other per-class structures used for efficient dispatch.
These rules are intended to faithfully reflect the JVMS definition of method selection, as proposed by JEP 181, in section 5.4.5.
...
Copyright © 2018 Oracle America, Inc. 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.
The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Oracle America, Inc. ("Oracle") and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement.
Subject to the terms and conditions of this license, including your compliance with Paragraphs 1 and 2 below, Oracle hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under Oracle's intellectual property rights to:
Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a significant portion of the Technology.
Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation:
does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented;
is clearly and prominently marked with the word "UNTESTED" or "EARLY ACCESS" or "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee's control; and
includes the following notice: "This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP."
The grant set forth above concerning your distribution of implementations of the specification is contingent upon your agreement to terminate development and distribution of your "early draft" implementation as soon as feasible following final completion of the specification. If you fail to do so, the foregoing grant shall be considered null and void.
No provision of this Agreement shall be understood to restrict your ability to make and distribute to third parties applications written to the Specification.
Other than this limited license, you acquire no right, title or interest in or to the Specification or any other Oracle intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from Oracle if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification.
"Licensor Name Space" means the public class or interface declarations whose names begin with "java", "javax", "com.oracle" or their equivalents in any subsequent naming convention adopted by Oracle through the Java Community Process, or any recognized successors or replacements thereof.
No right, title, or interest in or to any trademarks, service marks, or trade names of Oracle or Oracle's licensors is granted hereunder. Oracle, the Oracle logo, Java are trademarks or registered trademarks of Oracle USA, Inc. in the U.S. and other countries.
THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY ORACLE. ORACLE MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product.
THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. ORACLE MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ORACLE OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF ORACLE AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
You will hold Oracle (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license.
If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).
You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification ("Feedback"). To the extent that you provide Oracle with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Oracle a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof.
Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.
The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other countries. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee.
This Agreement is the parties' entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be binding, unless in writing and signed by an authorized representative of each party.