1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/lang/invoke/package-info.java Sat Aug 09 11:11:13 2014 +0200
1.3 @@ -0,0 +1,211 @@
1.4 +/*
1.5 + * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +/**
1.30 + * The {@code java.lang.invoke} package contains dynamic language support provided directly by
1.31 + * the Java core class libraries and virtual machine.
1.32 + *
1.33 + * <p>
1.34 + * As described in the Java Virtual Machine Specification,
1.35 + * certain types in this package have special relations to dynamic
1.36 + * language support in the virtual machine:
1.37 + * <ul>
1.38 + * <li>The class {@link java.lang.invoke.MethodHandle MethodHandle} contains
1.39 + * <a href="MethodHandle.html#sigpoly">signature polymorphic methods</a>
1.40 + * which can be linked regardless of their type descriptor.
1.41 + * Normally, method linkage requires exact matching of type descriptors.
1.42 + * </li>
1.43 + *
1.44 + * <li>The JVM bytecode format supports immediate constants of
1.45 + * the classes {@link java.lang.invoke.MethodHandle MethodHandle} and {@link java.lang.invoke.MethodType MethodType}.
1.46 + * </li>
1.47 + * </ul>
1.48 + *
1.49 + * <h1><a name="jvm_mods"></a>Summary of relevant Java Virtual Machine changes</h1>
1.50 + * The following low-level information summarizes relevant parts of the
1.51 + * Java Virtual Machine specification. For full details, please see the
1.52 + * current version of that specification.
1.53 + *
1.54 + * Each occurrence of an {@code invokedynamic} instruction is called a <em>dynamic call site</em>.
1.55 + * <h2><a name="indyinsn"></a>{@code invokedynamic} instructions</h2>
1.56 + * A dynamic call site is originally in an unlinked state. In this state, there is
1.57 + * no target method for the call site to invoke.
1.58 + * <p>
1.59 + * Before the JVM can execute a dynamic call site (an {@code invokedynamic} instruction),
1.60 + * the call site must first be <em>linked</em>.
1.61 + * Linking is accomplished by calling a <em>bootstrap method</em>
1.62 + * which is given the static information content of the call site,
1.63 + * and which must produce a {@link java.lang.invoke.MethodHandle method handle}
1.64 + * that gives the behavior of the call site.
1.65 + * <p>
1.66 + * Each {@code invokedynamic} instruction statically specifies its own
1.67 + * bootstrap method as a constant pool reference.
1.68 + * The constant pool reference also specifies the call site's name and type descriptor,
1.69 + * just like {@code invokevirtual} and the other invoke instructions.
1.70 + * <p>
1.71 + * Linking starts with resolving the constant pool entry for the
1.72 + * bootstrap method, and resolving a {@link java.lang.invoke.MethodType MethodType} object for
1.73 + * the type descriptor of the dynamic call site.
1.74 + * This resolution process may trigger class loading.
1.75 + * It may therefore throw an error if a class fails to load.
1.76 + * This error becomes the abnormal termination of the dynamic
1.77 + * call site execution.
1.78 + * Linkage does not trigger class initialization.
1.79 + * <p>
1.80 + * The bootstrap method is invoked on at least three values:
1.81 + * <ul>
1.82 + * <li>a {@code MethodHandles.Lookup}, a lookup object on the <em>caller class</em> in which dynamic call site occurs </li>
1.83 + * <li>a {@code String}, the method name mentioned in the call site </li>
1.84 + * <li>a {@code MethodType}, the resolved type descriptor of the call </li>
1.85 + * <li>optionally, between 1 and 251 additional static arguments taken from the constant pool </li>
1.86 + * </ul>
1.87 + * Invocation is as if by
1.88 + * {@link java.lang.invoke.MethodHandle#invoke MethodHandle.invoke}.
1.89 + * The returned result must be a {@link java.lang.invoke.CallSite CallSite} (or a subclass).
1.90 + * The type of the call site's target must be exactly equal to the type
1.91 + * derived from the dynamic call site's type descriptor and passed to
1.92 + * the bootstrap method.
1.93 + * The call site then becomes permanently linked to the dynamic call site.
1.94 + * <p>
1.95 + * As documented in the JVM specification, all failures arising from
1.96 + * the linkage of a dynamic call site are reported
1.97 + * by a {@link java.lang.BootstrapMethodError BootstrapMethodError},
1.98 + * which is thrown as the abnormal termination of the dynamic call
1.99 + * site execution.
1.100 + * If this happens, the same error will the thrown for all subsequent
1.101 + * attempts to execute the dynamic call site.
1.102 + *
1.103 + * <h2>timing of linkage</h2>
1.104 + * A dynamic call site is linked just before its first execution.
1.105 + * The bootstrap method call implementing the linkage occurs within
1.106 + * a thread that is attempting a first execution.
1.107 + * <p>
1.108 + * If there are several such threads, the bootstrap method may be
1.109 + * invoked in several threads concurrently.
1.110 + * Therefore, bootstrap methods which access global application
1.111 + * data must take the usual precautions against race conditions.
1.112 + * In any case, every {@code invokedynamic} instruction is either
1.113 + * unlinked or linked to a unique {@code CallSite} object.
1.114 + * <p>
1.115 + * In an application which requires dynamic call sites with individually
1.116 + * mutable behaviors, their bootstrap methods should produce distinct
1.117 + * {@link java.lang.invoke.CallSite CallSite} objects, one for each linkage request.
1.118 + * Alternatively, an application can link a single {@code CallSite} object
1.119 + * to several {@code invokedynamic} instructions, in which case
1.120 + * a change to the target method will become visible at each of
1.121 + * the instructions.
1.122 + * <p>
1.123 + * If several threads simultaneously execute a bootstrap method for a single dynamic
1.124 + * call site, the JVM must choose one {@code CallSite} object and install it visibly to
1.125 + * all threads. Any other bootstrap method calls are allowed to complete, but their
1.126 + * results are ignored, and their dynamic call site invocations proceed with the originally
1.127 + * chosen target object.
1.128 +
1.129 + * <p style="font-size:smaller;">
1.130 + * <em>Discussion:</em>
1.131 + * These rules do not enable the JVM to duplicate dynamic call sites,
1.132 + * or to issue “causeless” bootstrap method calls.
1.133 + * Every dynamic call site transitions at most once from unlinked to linked,
1.134 + * just before its first invocation.
1.135 + * There is no way to undo the effect of a completed bootstrap method call.
1.136 + *
1.137 + * <h2>types of bootstrap methods</h2>
1.138 + * As long as each bootstrap method can be correctly invoked
1.139 + * by {@code MethodHandle.invoke}, its detailed type is arbitrary.
1.140 + * For example, the first argument could be {@code Object}
1.141 + * instead of {@code MethodHandles.Lookup}, and the return type
1.142 + * could also be {@code Object} instead of {@code CallSite}.
1.143 + * (Note that the types and number of the stacked arguments limit
1.144 + * the legal kinds of bootstrap methods to appropriately typed
1.145 + * static methods and constructors of {@code CallSite} subclasses.)
1.146 + * <p>
1.147 + * If a given {@code invokedynamic} instruction specifies no static arguments,
1.148 + * the instruction's bootstrap method will be invoked on three arguments,
1.149 + * conveying the instruction's caller class, name, and method type.
1.150 + * If the {@code invokedynamic} instruction specifies one or more static arguments,
1.151 + * those values will be passed as additional arguments to the method handle.
1.152 + * (Note that because there is a limit of 255 arguments to any method,
1.153 + * at most 251 extra arguments can be supplied, since the bootstrap method
1.154 + * handle itself and its first three arguments must also be stacked.)
1.155 + * The bootstrap method will be invoked as if by either {@code MethodHandle.invoke}
1.156 + * or {@code invokeWithArguments}. (There is no way to tell the difference.)
1.157 + * <p>
1.158 + * The normal argument conversion rules for {@code MethodHandle.invoke} apply to all stacked arguments.
1.159 + * For example, if a pushed value is a primitive type, it may be converted to a reference by boxing conversion.
1.160 + * If the bootstrap method is a variable arity method (its modifier bit {@code 0x0080} is set),
1.161 + * then some or all of the arguments specified here may be collected into a trailing array parameter.
1.162 + * (This is not a special rule, but rather a useful consequence of the interaction
1.163 + * between {@code CONSTANT_MethodHandle} constants, the modifier bit for variable arity methods,
1.164 + * and the {@link java.lang.invoke.MethodHandle#asVarargsCollector asVarargsCollector} transformation.)
1.165 + * <p>
1.166 + * Given these rules, here are examples of legal bootstrap method declarations,
1.167 + * given various numbers {@code N} of extra arguments.
1.168 + * The first rows (marked {@code *}) will work for any number of extra arguments.
1.169 + * <table border=1 cellpadding=5 summary="Static argument types">
1.170 + * <tr><th>N</th><th>sample bootstrap method</th></tr>
1.171 + * <tr><td>*</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr>
1.172 + * <tr><td>*</td><td><code>CallSite bootstrap(Object... args)</code></td></tr>
1.173 + * <tr><td>*</td><td><code>CallSite bootstrap(Object caller, Object... nameAndTypeWithArgs)</code></td></tr>
1.174 + * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type)</code></td></tr>
1.175 + * <tr><td>0</td><td><code>CallSite bootstrap(Lookup caller, Object... nameAndType)</code></td></tr>
1.176 + * <tr><td>1</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object arg)</code></td></tr>
1.177 + * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, Object... args)</code></td></tr>
1.178 + * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String... args)</code></td></tr>
1.179 + * <tr><td>2</td><td><code>CallSite bootstrap(Lookup caller, String name, MethodType type, String x, int y)</code></td></tr>
1.180 + * </table>
1.181 + * The last example assumes that the extra arguments are of type
1.182 + * {@code CONSTANT_String} and {@code CONSTANT_Integer}, respectively.
1.183 + * The second-to-last example assumes that all extra arguments are of type
1.184 + * {@code CONSTANT_String}.
1.185 + * The other examples work with all types of extra arguments.
1.186 + * <p>
1.187 + * As noted above, the actual method type of the bootstrap method can vary.
1.188 + * For example, the fourth argument could be {@code MethodHandle},
1.189 + * if that is the type of the corresponding constant in
1.190 + * the {@code CONSTANT_InvokeDynamic} entry.
1.191 + * In that case, the {@code MethodHandle.invoke} call will pass the extra method handle
1.192 + * constant as an {@code Object}, but the type matching machinery of {@code MethodHandle.invoke}
1.193 + * will cast the reference back to {@code MethodHandle} before invoking the bootstrap method.
1.194 + * (If a string constant were passed instead, by badly generated code, that cast would then fail,
1.195 + * resulting in a {@code BootstrapMethodError}.)
1.196 + * <p>
1.197 + * Note that, as a consequence of the above rules, the bootstrap method may accept a primitive
1.198 + * argument, if it can be represented by a constant pool entry.
1.199 + * However, arguments of type {@code boolean}, {@code byte}, {@code short}, or {@code char}
1.200 + * cannot be created for bootstrap methods, since such constants cannot be directly
1.201 + * represented in the constant pool, and the invocation of the bootstrap method will
1.202 + * not perform the necessary narrowing primitive conversions.
1.203 + * <p>
1.204 + * Extra bootstrap method arguments are intended to allow language implementors
1.205 + * to safely and compactly encode metadata.
1.206 + * In principle, the name and extra arguments are redundant,
1.207 + * since each call site could be given its own unique bootstrap method.
1.208 + * Such a practice is likely to produce large class files and constant pools.
1.209 + *
1.210 + * @author John Rose, JSR 292 EG
1.211 + * @since 1.7
1.212 + */
1.213 +
1.214 +package java.lang.invoke;