diff -r eca8e9c3ec3e -r cd50c1894ce5 rt/emul/compact/src/main/java/java/lang/invoke/package-info.java --- a/rt/emul/compact/src/main/java/java/lang/invoke/package-info.java Sun Aug 17 20:09:05 2014 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,211 +0,0 @@ -/* - * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ - -/** - * The {@code java.lang.invoke} package contains dynamic language support provided directly by - * the Java core class libraries and virtual machine. - * - *
- * As described in the Java Virtual Machine Specification, - * certain types in this package have special relations to dynamic - * language support in the virtual machine: - *
- * Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction), - * the call site must first be linked. - * Linking is accomplished by calling a bootstrap method - * which is given the static information content of the call site, - * and which must produce a {@link java.lang.invoke.MethodHandle method handle} - * that gives the behavior of the call site. - *
- * Each {@code invokedynamic} instruction statically specifies its own - * bootstrap method as a constant pool reference. - * The constant pool reference also specifies the call site's name and type descriptor, - * just like {@code invokevirtual} and the other invoke instructions. - *
- * Linking starts with resolving the constant pool entry for the - * bootstrap method, and resolving a {@link java.lang.invoke.MethodType MethodType} object for - * the type descriptor of the dynamic call site. - * This resolution process may trigger class loading. - * It may therefore throw an error if a class fails to load. - * This error becomes the abnormal termination of the dynamic - * call site execution. - * Linkage does not trigger class initialization. - *
- * The bootstrap method is invoked on at least three values: - *
- * As documented in the JVM specification, all failures arising from - * the linkage of a dynamic call site are reported - * by a {@link java.lang.BootstrapMethodError BootstrapMethodError}, - * which is thrown as the abnormal termination of the dynamic call - * site execution. - * If this happens, the same error will the thrown for all subsequent - * attempts to execute the dynamic call site. - * - *
- * If there are several such threads, the bootstrap method may be - * invoked in several threads concurrently. - * Therefore, bootstrap methods which access global application - * data must take the usual precautions against race conditions. - * In any case, every {@code invokedynamic} instruction is either - * unlinked or linked to a unique {@code CallSite} object. - *
- * In an application which requires dynamic call sites with individually - * mutable behaviors, their bootstrap methods should produce distinct - * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request. - * Alternatively, an application can link a single {@code CallSite} object - * to several {@code invokedynamic} instructions, in which case - * a change to the target method will become visible at each of - * the instructions. - *
- * If several threads simultaneously execute a bootstrap method for a single dynamic - * call site, the JVM must choose one {@code CallSite} object and install it visibly to - * all threads. Any other bootstrap method calls are allowed to complete, but their - * results are ignored, and their dynamic call site invocations proceed with the originally - * chosen target object. - - *
- * Discussion: - * These rules do not enable the JVM to duplicate dynamic call sites, - * or to issue “causeless” bootstrap method calls. - * Every dynamic call site transitions at most once from unlinked to linked, - * just before its first invocation. - * There is no way to undo the effect of a completed bootstrap method call. - * - *
- * If a given {@code invokedynamic} instruction specifies no static arguments, - * the instruction's bootstrap method will be invoked on three arguments, - * conveying the instruction's caller class, name, and method type. - * If the {@code invokedynamic} instruction specifies one or more static arguments, - * those values will be passed as additional arguments to the method handle. - * (Note that because there is a limit of 255 arguments to any method, - * at most 251 extra arguments can be supplied, since the bootstrap method - * handle itself and its first three arguments must also be stacked.) - * The bootstrap method will be invoked as if by either {@code MethodHandle.invoke} - * or {@code invokeWithArguments}. (There is no way to tell the difference.) - *
- * The normal argument conversion rules for {@code MethodHandle.invoke} apply to all stacked arguments. - * For example, if a pushed value is a primitive type, it may be converted to a reference by boxing conversion. - * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set), - * then some or all of the arguments specified here may be collected into a trailing array parameter. - * (This is not a special rule, but rather a useful consequence of the interaction - * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods, - * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.) - *
- * Given these rules, here are examples of legal bootstrap method declarations, - * given various numbers {@code N} of extra arguments. - * The first rows (marked {@code *}) will work for any number of extra arguments. - *
N | sample bootstrap method |
---|---|
* | CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args) |
* | CallSite bootstrap(Object... args) |
* | CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs) |
0 | CallSite bootstrap(Lookup caller, String name, MethodType type) |
0 | CallSite bootstrap(Lookup caller, Object... nameAndType) |
1 | CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg) |
2 | CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args) |
2 | CallSite bootstrap(Lookup caller, String name, MethodType type, String... args) |
2 | CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y) |
- * As noted above, the actual method type of the bootstrap method can vary. - * For example, the fourth argument could be {@code MethodHandle}, - * if that is the type of the corresponding constant in - * the {@code CONSTANT_InvokeDynamic} entry. - * In that case, the {@code MethodHandle.invoke} call will pass the extra method handle - * constant as an {@code Object}, but the type matching machinery of {@code MethodHandle.invoke} - * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method. - * (If a string constant were passed instead, by badly generated code, that cast would then fail, - * resulting in a {@code BootstrapMethodError}.) - *
- * Note that, as a consequence of the above rules, the bootstrap method may accept a primitive - * argument, if it can be represented by a constant pool entry. - * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char} - * cannot be created for bootstrap methods, since such constants cannot be directly - * represented in the constant pool, and the invocation of the bootstrap method will - * not perform the necessary narrowing primitive conversions. - *
- * Extra bootstrap method arguments are intended to allow language implementors - * to safely and compactly encode metadata. - * In principle, the name and extra arguments are redundant, - * since each call site could be given its own unique bootstrap method. - * Such a practice is likely to produce large class files and constant pools. - * - * @author John Rose, JSR 292 EG - * @since 1.7 - */ - -package java.lang.invoke;