* {@code CallSite} is an abstract class which does not allow * direct subclassing by users. It has three immediate, * concrete subclasses that may be either instantiated or subclassed. *
* A non-constant call site may be relinked by changing its target. * The new target must have the same {@linkplain MethodHandle#type() type} * as the previous target. * Thus, though a call site can be relinked to a series of * successive targets, it cannot change its type. *
* Here is a sample use of call sites and bootstrap methods which links every * dynamic call site to print its arguments:
static void test() throws Throwable {
// THE FOLLOWING LINE IS PSEUDOCODE FOR A JVM INSTRUCTION
InvokeDynamic[#bootstrapDynamic].baz("baz arg", 2, 3.14);
}
private static void printArgs(Object... args) {
System.out.println(java.util.Arrays.deepToString(args));
}
private static final MethodHandle printArgs;
static {
MethodHandles.Lookup lookup = MethodHandles.lookup();
Class thisClass = lookup.lookupClass(); // (who am I?)
printArgs = lookup.findStatic(thisClass,
"printArgs", MethodType.methodType(void.class, Object[].class));
}
private static CallSite bootstrapDynamic(MethodHandles.Lookup caller, String name, MethodType type) {
// ignore caller and name, but match the type:
return new ConstantCallSite(printArgs.asType(type));
}
* Before this {@code CallSite} object is returned from a bootstrap method, * it is usually provided with a more useful target method, * via a call to {@link CallSite#setTarget(MethodHandle) setTarget}. * @throws NullPointerException if the proposed type is null */ /*package-private*/ CallSite(MethodType type) { target = type.invokers().uninitializedCallSite(); } /** * Make a call site object equipped with an initial target method handle. * @param target the method handle which will be the initial target of the call site * @throws NullPointerException if the proposed target is null */ /*package-private*/ CallSite(MethodHandle target) { target.type(); // null check this.target = target; } /** * Make a call site object equipped with an initial target method handle. * @param targetType the desired type of the call site * @param createTargetHook a hook which will bind the call site to the target method handle * @throws WrongMethodTypeException if the hook cannot be invoked on the required arguments, * or if the target returned by the hook is not of the given {@code targetType} * @throws NullPointerException if the hook returns a null value * @throws ClassCastException if the hook returns something other than a {@code MethodHandle} * @throws Throwable anything else thrown by the the hook function */ /*package-private*/ CallSite(MethodType targetType, MethodHandle createTargetHook) throws Throwable { this(targetType); ConstantCallSite selfCCS = (ConstantCallSite) this; MethodHandle boundTarget = (MethodHandle) createTargetHook.invokeWithArguments(selfCCS); checkTargetChange(this.target, boundTarget); this.target = boundTarget; } /** * Returns the type of this call site's target. * Although targets may change, any call site's type is permanent, and can never change to an unequal type. * The {@code setTarget} method enforces this invariant by refusing any new target that does * not have the previous target's type. * @return the type of the current target, which is also the type of any future target */ public MethodType type() { // warning: do not call getTarget here, because CCS.getTarget can throw IllegalStateException return target.type(); } /** * Returns the target method of the call site, according to the * behavior defined by this call site's specific class. * The immediate subclasses of {@code CallSite} document the * class-specific behaviors of this method. * * @return the current linkage state of the call site, its target method handle * @see ConstantCallSite * @see VolatileCallSite * @see #setTarget * @see ConstantCallSite#getTarget * @see MutableCallSite#getTarget * @see VolatileCallSite#getTarget */ public abstract MethodHandle getTarget(); /** * Updates the target method of this call site, according to the * behavior defined by this call site's specific class. * The immediate subclasses of {@code CallSite} document the * class-specific behaviors of this method. *
* The type of the new target must be {@linkplain MethodType#equals equal to} * the type of the old target. * * @param newTarget the new target * @throws NullPointerException if the proposed new target is null * @throws WrongMethodTypeException if the proposed new target * has a method type that differs from the previous target * @see CallSite#getTarget * @see ConstantCallSite#setTarget * @see MutableCallSite#setTarget * @see VolatileCallSite#setTarget */ public abstract void setTarget(MethodHandle newTarget); void checkTargetChange(MethodHandle oldTarget, MethodHandle newTarget) { MethodType oldType = oldTarget.type(); MethodType newType = newTarget.type(); // null check! if (!newType.equals(oldType)) throw wrongTargetType(newTarget, oldType); } private static WrongMethodTypeException wrongTargetType(MethodHandle target, MethodType type) { return new WrongMethodTypeException(String.valueOf(target)+" should be of type "+type); } /** * Produces a method handle equivalent to an invokedynamic instruction * which has been linked to this call site. *
* This method is equivalent to the following code: *
* MethodHandle getTarget, invoker, result;
* getTarget = MethodHandles.publicLookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class));
* invoker = MethodHandles.exactInvoker(this.type());
* result = MethodHandles.foldArguments(invoker, getTarget)
*