Home » openjdk-7 » java.lang.invoke » [javadoc | source]
java.lang.invoke
abstract public class: CallSite [javadoc | source]
java.lang.Object
   java.lang.invoke.CallSite

Direct Known Subclasses:
    ConstantCallSite, VolatileCallSite, MutableCallSite

A {@code CallSite} is a holder for a variable MethodHandle , which is called its {@code target}. An {@code invokedynamic} instruction linked to a {@code CallSite} delegates all calls to the site's current target. A {@code CallSite} may be associated with several {@code invokedynamic} instructions, or it may be "free floating", associated with none. In any case, it may be invoked through an associated method handle called its {@linkplain #dynamicInvoker dynamic invoker}.

{@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));
}
Field Summary
 MethodHandle target     
Constructor:
 CallSite(MethodType type) 
    Make a blank call site object with the given method type. An initial target method is supplied which will throw an IllegalStateException if called.

    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 setTarget .

    Throws:
    NullPointerException - if the proposed type is null
 CallSite(MethodHandle target) 
    Make a call site object equipped with an initial target method handle.
    Parameters:
    target - the method handle which will be the initial target of the call site
    Throws:
    NullPointerException - if the proposed target is null
 CallSite(MethodType targetType,
    MethodHandle createTargetHook) throws Throwable 
    Make a call site object equipped with an initial target method handle.
    Parameters:
    targetType - the desired type of the call site
    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}
    NullPointerException - if the hook returns a null value
    ClassCastException - if the hook returns something other than a {@code MethodHandle}
    Throwable - anything else thrown by the the hook function
Method from java.lang.invoke.CallSite Summary:
checkTargetChange,   dynamicInvoker,   getTarget,   getTargetVolatile,   initializeFromJVM,   makeDynamicInvoker,   makeSite,   setTarget,   setTargetNormal,   setTargetVolatile,   type,   uninitializedCallSite
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from java.lang.invoke.CallSite Detail:
  void checkTargetChange(MethodHandle oldTarget,
    MethodHandle newTarget) 
 abstract public MethodHandle dynamicInvoker()
    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)
    
 abstract public MethodHandle getTarget()
    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.
 MethodHandle getTargetVolatile() 
  void initializeFromJVM(String name,
    MethodType type,
    MemberName callerMethod,
    int callerBCI) 
    Called from JVM (or low-level Java code) after the BSM returns the newly created CallSite. The parameters are JVM-specific.
 MethodHandle makeDynamicInvoker() 
 static CallSite makeSite(MethodHandle bootstrapMethod,
    String name,
    MethodType type,
    Object info,
    MemberName callerMethod,
    int callerBCI) 
 abstract public  void setTarget(MethodHandle newTarget)
    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.

  void setTargetNormal(MethodHandle newTarget) 
  void setTargetVolatile(MethodHandle newTarget) 
 public MethodType type() 
    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.
 static Empty uninitializedCallSite() 
    This guy is rolled into the default target if a MethodType is supplied to the constructor.