1.1 --- a/make/common/Release.gmk Mon May 11 12:08:15 2009 -0700
1.2 +++ b/make/common/Release.gmk Mon May 11 21:09:58 2009 -0700
1.3 @@ -52,6 +52,9 @@
1.4 com.sun.java.swing.plaf.motif \
1.5 com.sun.java.swing.plaf.gtk
1.6
1.7 +# This is a stopgap until 6839872 is fixed.
1.8 +EXCLUDE_PROPWARN_PKGS += sun.dyn
1.9 +
1.10 # 64-bit solaris has a few special cases. We define the variable
1.11 # SOLARIS64 for use in this Makefile to easily test those cases
1.12 ifeq ($(PLATFORM), solaris)
2.1 --- a/make/docs/CORE_PKGS.gmk Mon May 11 12:08:15 2009 -0700
2.2 +++ b/make/docs/CORE_PKGS.gmk Mon May 11 21:09:58 2009 -0700
2.3 @@ -97,6 +97,7 @@
2.4 java.awt.print \
2.5 java.beans \
2.6 java.beans.beancontext \
2.7 + java.dyn \
2.8 java.io \
2.9 java.lang \
2.10 java.lang.annotation \
3.1 --- a/src/share/classes/java/dyn/CallSite.java Mon May 11 12:08:15 2009 -0700
3.2 +++ b/src/share/classes/java/dyn/CallSite.java Mon May 11 21:09:58 2009 -0700
3.3 @@ -28,18 +28,28 @@
3.4 import sun.dyn.util.BytecodeName;
3.5
3.6 /**
3.7 - * An <code>invokedynamic</code> call site, as reified to the bootstrap method.
3.8 - * Every instance of a call site corresponds to a distinct instance
3.9 - * of the <code>invokedynamic</code> instruction.
3.10 - * Call sites have state, one reference word, called the <code>target</code>,
3.11 - * and typed as a {@link MethodHandle}. When this state is null (as it is
3.12 - * initially) the call site is in the unlinked state. Otherwise, it is said
3.13 - * to be linked to its target.
3.14 + * An {@code invokedynamic} call site, as reified by the
3.15 + * containing class's bootstrap method.
3.16 + * Every call site object corresponds to a distinct instance
3.17 + * of the <code>invokedynamic</code> instruction, and vice versa.
3.18 + * Every call site has one state variable, called the {@code target}.
3.19 + * It is typed as a {@link MethodHandle}. This state is never null, and
3.20 + * it is the responsibility of the bootstrap method to produce call sites
3.21 + * which have been pre-linked to an initial target method.
3.22 * <p>
3.23 - * When an unlinked call site is executed, a bootstrap routine is called
3.24 - * to finish the execution of the call site, and optionally to link
3.25 - * the call site.
3.26 + * (Note: The bootstrap method may elect to produce call sites of a
3.27 + * language-specific subclass of {@code CallSite}. In such a case,
3.28 + * the subclass may claim responsibility for initializing its target to
3.29 + * a non-null value, by overriding {@link #initialTarget}.)
3.30 * <p>
3.31 + * An {@code invokedynamic} instruction which has not yet been executed
3.32 + * is said to be <em>unlinked</em>. When an unlinked call site is executed,
3.33 + * the containing class's bootstrap method is called to manufacture a call site,
3.34 + * for the instruction. If the bootstrap method does not assign a non-null
3.35 + * value to the new call site's target variable, the method {@link #initialTarget}
3.36 + * is called to produce the new call site's first target method.
3.37 + * <p>
3.38 + * @see Linkage#registerBootstrapMethod(java.lang.Class, java.dyn.MethodHandle)
3.39 * @author John Rose, JSR 292 EG
3.40 */
3.41 public class CallSite {
3.42 @@ -52,6 +62,15 @@
3.43 final String name;
3.44 final MethodType type;
3.45
3.46 + /**
3.47 + * Make a call site given the parameters from a call to the bootstrap method.
3.48 + * The resulting call site is in an unlinked state, which means that before
3.49 + * it is returned from a bootstrap method call it must be provided with
3.50 + * a target method via a call to {@link CallSite#setTarget}.
3.51 + * @param caller the class in which the relevant {@code invokedynamic} instruction occurs
3.52 + * @param name the name specified by the {@code invokedynamic} instruction
3.53 + * @param type the method handle type derived from descriptor of the {@code invokedynamic} instruction
3.54 + */
3.55 public CallSite(Object caller, String name, MethodType type) {
3.56 this.caller = caller;
3.57 this.name = name;
3.58 @@ -73,7 +92,9 @@
3.59 * <p>
3.60 * If the bootstrap method itself does not initialize the call site,
3.61 * this method must be overridden, because it just raises an
3.62 - * {@code InvokeDynamicBootstrapError}.
3.63 + * {@code InvokeDynamicBootstrapError}, which in turn causes the
3.64 + * linkage of the {@code invokedynamic} instruction to terminate
3.65 + * abnormally.
3.66 */
3.67 protected MethodHandle initialTarget() {
3.68 throw new InvokeDynamicBootstrapError("target must be initialized before call site is linked: "+this);
3.69 @@ -81,7 +102,7 @@
3.70
3.71 /**
3.72 * Report the current linkage state of the call site. (This is mutable.)
3.73 - * The value is null if and only if the call site is currently unlinked.
3.74 + * The value maybe null only if the call site is currently unlinked.
3.75 * When a linked call site is invoked, the target method is used directly.
3.76 * When an unlinked call site is invoked, its bootstrap method receives
3.77 * the call, as if via {@link Linkage#bootstrapInvokeDynamic}.
3.78 @@ -113,8 +134,9 @@
3.79 * into the bootstrap method and/or the target methods used
3.80 * at any given call site.
3.81 * @param target the new target, or null if it is to be unlinked
3.82 - * @throws WrongMethodTypeException if the new target is not null
3.83 - * and has a method type that differs from the call site's {@link #type}
3.84 + * @throws NullPointerException if the proposed new target is null
3.85 + * @throws WrongMethodTypeException if the proposed new target
3.86 + * has a method type that differs from the call site's {@link #type()}
3.87 */
3.88 public void setTarget(MethodHandle target) {
3.89 checkTarget(target);
3.90 @@ -122,6 +144,7 @@
3.91 }
3.92
3.93 protected void checkTarget(MethodHandle target) {
3.94 + target.type(); // provoke NPE
3.95 if (!canSetTarget(target))
3.96 throw new WrongMethodTypeException(String.valueOf(target));
3.97 }
3.98 @@ -132,7 +155,7 @@
3.99
3.100 /**
3.101 * Report the class containing the call site.
3.102 - * This is immutable static context.
3.103 + * This is an immutable property of the call site, set from the first argument to the constructor.
3.104 * @return class containing the call site
3.105 */
3.106 public Class<?> callerClass() {
3.107 @@ -141,7 +164,7 @@
3.108
3.109 /**
3.110 * Report the method name specified in the {@code invokedynamic} instruction.
3.111 - * This is immutable static context.
3.112 + * This is an immutable property of the call site, set from the second argument to the constructor.
3.113 * <p>
3.114 * Note that the name is a JVM bytecode name, and as such can be any
3.115 * non-empty string, as long as it does not contain certain "dangerous"
3.116 @@ -187,7 +210,7 @@
3.117 * which are derived from its bytecode-level invocation descriptor.
3.118 * The types are packaged into a {@link MethodType}.
3.119 * Any linked target of this call site must be exactly this method type.
3.120 - * This is immutable static context.
3.121 + * This is an immutable property of the call site, set from the third argument to the constructor.
3.122 * @return method type specified by the call site
3.123 */
3.124 public MethodType type() {
4.1 --- a/src/share/classes/java/dyn/InvokeDynamic.java Mon May 11 12:08:15 2009 -0700
4.2 +++ b/src/share/classes/java/dyn/InvokeDynamic.java Mon May 11 21:09:58 2009 -0700
4.3 @@ -26,10 +26,25 @@
4.4 package java.dyn;
4.5
4.6 /**
4.7 - * Syntactic marker interface to request javac to emit an {@code invokedynamic} instruction.
4.8 + * Syntactic marker to request javac to emit an {@code invokedynamic} instruction.
4.9 + * An {@code invokedynamic} instruction is a 5-byte bytecoded instruction
4.10 + * which begins with an opcode byte of value 186 ({@code 0xBA}),
4.11 + * and is followed by a two-byte index of a {@code NameAndType} constant
4.12 + * pool entry, then by two zero bytes. The constant pool reference gives
4.13 + * the method name and argument and return types of the call site; there
4.14 + * is no other information provided at the call site.
4.15 * <p>
4.16 - * This type has no particular meaning as a class or interface supertype, and can never be instantiated.
4.17 + * The {@code invokedynamic} instruction is incomplete without a target method.
4.18 + * The target method is a property of the reified call site object
4.19 + * (of type {@link CallSite}) which is in a one-to-one association with each
4.20 + * corresponding {@code invokedynamic} instruction. The call site object
4.21 + * is initially produced by a <em>bootstrap method</em> associated with
4.22 + * the call site, via the various overloadings of {@link Linkage#registerBootstrapMethod}.
4.23 + * <p>
4.24 + * The type {@code InvokeDynamic} has no particular meaning as a
4.25 + * class or interface supertype, or an object type; it can never be instantiated.
4.26 * Logically, it denotes a source of all dynamically typed methods.
4.27 + * It may be viewed as a pure syntactic marker (an importable one) of static calls.
4.28 * @author John Rose, JSR 292 EG
4.29 */
4.30 public final class InvokeDynamic {
5.1 --- a/src/share/classes/java/dyn/Linkage.java Mon May 11 12:08:15 2009 -0700
5.2 +++ b/src/share/classes/java/dyn/Linkage.java Mon May 11 21:09:58 2009 -0700
5.3 @@ -37,16 +37,19 @@
5.4 private Linkage() {} // do not instantiate
5.5
5.6 /**
5.7 - * Register a bootstrap method for use for a given caller class.
5.8 - * The method handle must be of a type equivalent to {@link Linkage#makeCallSite}.
5.9 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
5.10 + * Register a <em>bootstrap method</em> to use when linking a given caller class.
5.11 + * It must be a method handle of a type equivalent to {@link CallSite#CallSite}.
5.12 + * In other words, it must act as a factory method which accepts the arguments
5.13 + * to {@code CallSite}'s constructor (a class, a string, and a method type),
5.14 + * and returns a {@code CallSite} object (possibly of a subclass of {@code CallSite}).
5.15 * <p>
5.16 - * The operation will fail with an exception if any of the following conditions hold:
5.17 + * The registration will fail with an {@code IllegalStateException} if any of the following conditions hold:
5.18 * <ul>
5.19 * <li>The caller of this method is in a different package than the {@code callerClass},
5.20 * and there is a security manager, and its {@code checkPermission} call throws
5.21 * when passed {@link LinkagePermission}("registerBootstrapMethod",callerClass).
5.22 - * <li>The given class already has a bootstrap method, either from an embedded
5.23 - * {@code BootstrapInvokeDynamic} classfile attribute, or from a previous
5.24 + * <li>The given class already has a bootstrap method from a previous
5.25 * call to this method.
5.26 * <li>The given class is already fully initialized.
5.27 * <li>The given class is in the process of initialization, in another thread.
5.28 @@ -75,9 +78,10 @@
5.29 }
5.30
5.31 /**
5.32 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
5.33 * Simplified version of registerBootstrapMethod for self-registration,
5.34 * to be called from a static initializer.
5.35 - * Finds a static method of type (CallSite, Object[]) -> Object in the
5.36 + * Finds a static method of the required type in the
5.37 * given class, and installs it on the caller.
5.38 * @throws IllegalArgumentException if there is no such method
5.39 */
5.40 @@ -92,9 +96,10 @@
5.41 }
5.42
5.43 /**
5.44 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
5.45 * Simplified version of registerBootstrapMethod for self-registration,
5.46 * to be called from a static initializer.
5.47 - * Finds a static method of type (CallSite, Object[]) -> Object in the
5.48 + * Finds a static method of the required type in the
5.49 * caller's class, and installs it on the caller.
5.50 * @throws IllegalArgumentException if there is no such method
5.51 */
5.52 @@ -109,6 +114,7 @@
5.53 }
5.54
5.55 /**
5.56 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
5.57 * Report the bootstrap method registered for a given class.
5.58 * Returns null if the class has never yet registered a bootstrap method,
5.59 * or if the class has explicitly registered a null bootstrap method.
5.60 @@ -125,8 +131,10 @@
5.61 }
5.62 }
5.63
5.64 - /** The type of any bootstrap method is a three-argument method
5.65 - * {@code (Class<?>, String, MethodType)} returning a {@code CallSite}.
5.66 + /**
5.67 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
5.68 + * The type of any bootstrap method is a three-argument method
5.69 + * {@code (Class, String, MethodType)} returning a {@code CallSite}.
5.70 */
5.71 public static final MethodType BOOTSTRAP_METHOD_TYPE
5.72 = MethodType.make(CallSite.class,
5.73 @@ -140,6 +148,7 @@
5.74 new WeakHashMap<Class, MethodHandle>();
5.75
5.76 /**
5.77 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
5.78 * Invalidate all <code>invokedynamic</code> call sites everywhere.
5.79 * <p>
5.80 * When this method returns, every <code>invokedynamic</code> instruction
5.81 @@ -163,6 +172,7 @@
5.82 }
5.83
5.84 /**
5.85 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
5.86 * Invalidate all <code>invokedynamic</code> call sites associated
5.87 * with the given class.
5.88 * (These are exactly those sites which report the given class
6.1 --- a/src/share/classes/java/dyn/MethodHandles.java Mon May 11 12:08:15 2009 -0700
6.2 +++ b/src/share/classes/java/dyn/MethodHandles.java Mon May 11 21:09:58 2009 -0700
6.3 @@ -73,6 +73,7 @@
6.4 }
6.5
6.6 /**
6.7 + * <em>PROVISIONAL API, WORK IN PROGRESS:</em>
6.8 * A factory object for creating method handles, when the creation
6.9 * requires access checking. Method handles do not perform
6.10 * access checks when they are called; this is a major difference
6.11 @@ -108,8 +109,10 @@
6.12 * access. In any of these cases, an exception will be
6.13 * thrown from the attempted lookup.
6.14 * In general, the conditions under which a method handle may be
6.15 - * created for a method M are exactly as restrictive as the conditions
6.16 - * under which the lookup class could have compiled a call to M.
6.17 + * created for a method {@code M} are exactly as restrictive as the conditions
6.18 + * under which the lookup class could have compiled a call to {@code M}.
6.19 + * At least some of these error conditions are likely to be
6.20 + * represented by checked exceptions in the final version of this API.
6.21 */
6.22 public static final
6.23 class Lookup {
6.24 @@ -222,11 +225,11 @@
6.25
6.26 /**
6.27 * Produce an early-bound method handle for a virtual method,
6.28 - * or a handle for a constructor, as if called from an {@code invokespecial}
6.29 + * as if called from an {@code invokespecial}
6.30 * instruction from {@code caller}.
6.31 - * The type of the method handle will be that of the method or constructor,
6.32 + * The type of the method handle will be that of the method,
6.33 * with a suitably restricted receiver type (such as {@code caller}) prepended.
6.34 - * The method or constructor and all its argument types must be accessible
6.35 + * The method and all its argument types must be accessible
6.36 * to the caller.
6.37 * <p>
6.38 * When called, the handle will treat the first argument as a receiver,
7.1 --- a/src/share/classes/java/dyn/MethodType.java Mon May 11 12:08:15 2009 -0700
7.2 +++ b/src/share/classes/java/dyn/MethodType.java Mon May 11 21:09:58 2009 -0700
7.3 @@ -333,7 +333,7 @@
7.4
7.5 /** Convenience method for {@link #make(java.lang.Class, java.lang.Class[])}.
7.6 * Convert all wrapper types to their corresponding primitive types.
7.7 - * A return type of {@java.lang.Void} is changed to {@code void}.
7.8 + * A return type of {@code java.lang.Void} is changed to {@code void}.
7.9 * @return a version of the original type with all wrapper types replaced
7.10 */
7.11 public MethodType unwrap() {